gromov/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: перенести сборку в проекты
All checks were successful
CI/CD Pipeline / build (push) Successful in 39s
Details
CI/CD Pipeline / docker (push) Successful in 1m30s
Details
CI/CD Pipeline / deploy (push) Successful in 8s
Details

Browse Source 
- перенесены каноны и VitePress-конфиги в projects/<slug>

- добавлены корневой и проектные build.ts для сборки артефактов

- добавлены shared-библиотеки сборки в projects/_shared/lib

- обновлены CI, Dockerfile, package.json, gitignore и README

- удалена сборка frontend-агента
This commit is contained in:
Сергей Громов
2026-05-22 19:07:10 +03:00
parent a53c5fc1b1
commit bdb99ade62
117 changed files with 442 additions and 568 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
projects/_shared/docs/vitepress/HomeLink.vue Normal file
View File

@@ -0,0 +1,174 @@
<script setup lang="ts">
withDefaults(defineProps<{
variant?: 'back' | 'repo' | 'screen'
}>(), {
variant: 'back',
})
const repositoryUrl = 'https://gromlab.ru/gromov/docs'
</script>
<template>
<a
v-if="variant === 'back'"
class="docsNavLink docsBackLink"
href="/"
target="_self"
aria-label="Вернуться к списку документаций"
>
<span class="docsBackIcon" aria-hidden="true">←</span>
<span>К списку документаций</span>
</a>
<a
v-else-if="variant === 'repo'"
class="docsRepoLink"
:href="repositoryUrl"
target="_blank"
rel="noopener noreferrer"
aria-label="Открыть репозиторий"
title="Репозиторий"
>
<svg aria-hidden="true" viewBox="0 0 24 24">
<path d="M12 .5a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57l-.02-2.04c-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.01-.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 .5Z" />
</svg>
</a>
<nav v-else class="docsNavLinks" aria-label="Навигация документации">
<a
class="docsNavLink"
href="/"
target="_self"
aria-label="Вернуться к списку документаций"
>
<span class="docsBackIcon" aria-hidden="true">←</span>
<span>К списку документаций</span>
</a>
<a
class="docsNavLink"
:href="repositoryUrl"
target="_blank"
rel="noopener noreferrer"
aria-label="Открыть репозиторий документации"
>
<svg class="docsScreenRepoIcon" aria-hidden="true" viewBox="0 0 24 24">
<path d="M12 .5a12 12 0 0 0-3.8 23.38c.6.12.83-.26.83-.57l-.02-2.04c-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.01-.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 .5Z" />
</svg>
Репозиторий
</a>
</nav>
</template>
<style scoped>
.docsBackLink {
margin-left: 16px;
margin-right: 16px;
}
.docsNavLinks {
display: inline-flex;
align-items: center;
}
.docsNavLink {
display: inline-flex;
align-items: center;
gap: 6px;
color: var(--vp-c-text-2);
font-size: 13px;
font-weight: 600;
line-height: var(--vp-nav-height);
text-decoration: none;
transition: color 0.2s;
}
.docsBackIcon {
color: var(--vp-c-text-3);
font-size: 15px;
transition: color 0.2s;
}
.docsNavLink:hover {
color: var(--vp-c-brand-1);
}
.docsNavLink:hover .docsBackIcon {
color: var(--vp-c-brand-1);
}
.docsNavLink:focus-visible {
border-radius: 4px;
outline: 2px solid var(--vp-c-brand-1);
outline-offset: 2px;
}
.docsRepoLink {
display: inline-flex;
align-items: center;
justify-content: center;
width: 32px;
height: var(--vp-nav-height);
margin-left: 12px;
color: var(--vp-c-text-2);
transition: color 0.2s;
}
.docsRepoLink:hover {
color: var(--vp-c-brand-1);
}
.docsRepoLink:focus-visible {
border-radius: 6px;
outline: 2px solid var(--vp-c-brand-1);
outline-offset: 2px;
}
.docsRepoLink svg,
.docsScreenRepoIcon {
width: 18px;
height: 18px;
fill: currentColor;
}
.docsNavLinks {
align-items: stretch;
flex-direction: column;
gap: 0;
margin: 0;
padding: 8px 0 12px;
border-bottom: 1px solid var(--vp-c-divider);
}
.docsNavLinks .docsNavLink {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 12px 0;
color: var(--vp-c-text-1);
font-size: 14px;
line-height: 20px;
}
.docsScreenRepoIcon {
flex: 0 0 auto;
}
@media (max-width: 767px) {
.docsBackLink,
.docsRepoLink {
display: none;
}
}
@media (min-width: 768px) {
.docsNavLinks {
display: none;
}
}
@media (min-width: 960px) {
.docsBackLink {
margin-left: 24px;
}
}
</style>

15
projects/_shared/docs/vitepress/theme.ts Normal file
View File

@@ -0,0 +1,15 @@
import { h } from 'vue';
import DefaultTheme from 'vitepress/theme';
import type { Theme } from 'vitepress';
import HomeLink from './HomeLink.vue';
export default {
extends: DefaultTheme,
Layout() {
return h(DefaultTheme.Layout, null, {
'nav-bar-content-before': () => h(HomeLink, { variant: 'back' }),
'nav-bar-content-after': () => h(HomeLink, { variant: 'repo' }),
'nav-screen-content-before': () => h(HomeLink, { variant: 'screen' }),
});
},
} satisfies Theme;

18
projects/_shared/docs/vitepress/themeHead.ts Normal file
View File

@@ -0,0 +1,18 @@
import type { HeadConfig } from 'vitepress';
export const themeSyncHead: HeadConfig[] = [
[
'script',
{ id: 'sync-docs-theme' },
`;(() => {
const theme = localStorage.getItem('vitepress-theme-appearance')
if (theme) return
const legacyTheme = localStorage.getItem('all-docs-theme')
if (!legacyTheme) return
localStorage.setItem('vitepress-theme-appearance', legacyTheme === 'system' ? 'auto' : legacyTheme)
localStorage.removeItem('all-docs-theme')
})()`,
],
];

112
projects/_shared/lib/prepare-docs.ts Normal file
View File

@@ -0,0 +1,112 @@
import fs from 'node:fs';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
type Page = {
source: string;
target: string;
};
type RouteRewrite = {
from: string;
to: string;
};
type DocsConfig = {
mounts: Page[];
routeRewrites?: RouteRewrite[];
};
type ProjectConfig = {
slug: string;
docsDir: string;
};
const MD_LINK_RE = /\]\((?!#|[a-z][a-z0-9+.-]*:|\/\/)([^)\s]+)(#[^)]*)?\)/gi;
function normalizePath(value: string) {
return value.split(path.sep).join('/').replace(/^\.\//, '');
}
function formatRelativeMarkdownPath(fromTarget: string, toTarget: string) {
const relative = path.relative(path.dirname(fromTarget), toTarget).split(path.sep).join('/');
return relative.startsWith('.') ? relative : `./${relative}`;
}
async function loadDocsConfig(configPath: string) {
return (await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`)) as DocsConfig;
}
export async function prepareDocs(projectDir: string, config: ProjectConfig) {
const docsDir = path.join(projectDir, config.docsDir);
const contentDir = path.join(docsDir, 'content');
const docsConfig = await loadDocsConfig(path.join(docsDir, 'docs.config.ts'));
const targetBySource = new Map(
docsConfig.mounts.map((page) => [normalizePath(path.resolve(projectDir, page.source)), normalizePath(page.target)]),
);
const routeRewrites = [...(docsConfig.routeRewrites ?? [])].sort((a, b) => b.from.length - a.from.length);
function applyRouteRewrites(route: string) {
for (const rewrite of routeRewrites) {
if (route === rewrite.from || route.startsWith(`${rewrite.from}/`) || route.startsWith(`${rewrite.from}#`)) {
return `${rewrite.to}${route.slice(rewrite.from.length)}`;
}
}
return undefined;
}
function formatDocsRoute(route: string) {
const rewritten = applyRouteRewrites(route);
if (rewritten) return rewritten;
if (route === '/docs') return '/';
if (route.startsWith('/docs/')) return route.slice('/docs'.length);
return undefined;
}
function formatRelativeRoute(hrefPath: string, sourceDir: string) {
const sourcePath = normalizePath(path.relative(projectDir, path.resolve(sourceDir, hrefPath)));
if (sourcePath.startsWith('canons/')) return formatDocsRoute(`/docs/${sourcePath.slice('canons/'.length)}`);
return undefined;
}
function transformMarkdownLinks(content: string, page: Page) {
const sourceDir = path.dirname(path.resolve(projectDir, page.source));
return content.replace(MD_LINK_RE, (match, href: string, hash = '') => {
const [hrefPath, query = ''] = href.split('?');
const queryPart = query ? `?${query}` : '';
if (hrefPath.startsWith('/')) {
const route = formatDocsRoute(hrefPath) ?? applyRouteRewrites(hrefPath);
return route ? `](${route}${queryPart}${hash})` : match;
}
if (!hrefPath.endsWith('.md')) {
const route = formatRelativeRoute(hrefPath, sourceDir);
return route ? `](${route}${queryPart}${hash})` : match;
}
const target = targetBySource.get(normalizePath(path.resolve(sourceDir, hrefPath)));
if (!target) return match;
return `](${formatRelativeMarkdownPath(page.target, `${target}${queryPart}`)}${hash})`;
});
}
fs.rmSync(contentDir, { recursive: true, force: true });
fs.mkdirSync(contentDir, { recursive: true });
for (const page of docsConfig.mounts) {
const sourcePath = path.resolve(projectDir, page.source);
const targetPath = path.join(contentDir, page.target);
if (!fs.existsSync(sourcePath)) throw new Error(`Не найден канон: ${sourcePath}`);
fs.mkdirSync(path.dirname(targetPath), { recursive: true });
fs.writeFileSync(targetPath, transformMarkdownLinks(fs.readFileSync(sourcePath, 'utf8'), page), 'utf8');
console.log(`${page.target} -> ${path.relative(projectDir, sourcePath)}`);
}
console.log(`Подготовлен VitePress content для ${config.slug}: ${docsConfig.mounts.length} страниц`);
}

51
projects/_shared/lib/root-llms.ts Normal file
View File

@@ -0,0 +1,51 @@
import fs from 'node:fs';
import path from 'node:path';
import { docs } from '../../../src/config/docs.config';
const siteTitle = 'Документация';
const siteDescription = 'Единое пространство для идей, черновиков и первых версий документаций, которые ещё формируются и постепенно становятся самостоятельными материалами.';
function formatMarkdownLink(label: string, href: string, description: string) {
return `- [${label}](${href}): ${description}`;
}
function findDocLink(doc: (typeof docs)[number], label: string) {
return doc.links.find((link) => link.label === label);
}
export function generateRootLlms(rootDir = process.cwd()) {
const publicDir = path.join(rootDir, 'public');
const llmsPath = path.join(publicDir, 'llms.txt');
const content = [
`# ${siteTitle}`,
'',
`> ${siteDescription}`,
'',
'Этот файл является корневой картой документаций. Для работы с конкретным направлением используйте его собственный `llms.txt`.',
'',
'## Documentation',
'',
...docs
.map((doc) => {
const link = findDocLink(doc, 'llms.txt');
return link ? formatMarkdownLink(doc.title, link.href, doc.description) : undefined;
})
.filter(Boolean),
'',
'## Optional',
'',
...docs
.map((doc) => {
const link = findDocLink(doc, 'llms-full.txt');
return link ? formatMarkdownLink(`${doc.title} full`, link.href, `Полный bundle документации: ${doc.label.toLowerCase()}.`) : undefined;
})
.filter(Boolean),
'',
].join('\n');
fs.mkdirSync(publicDir, { recursive: true });
fs.writeFileSync(llmsPath, content, 'utf8');
console.log(`Сгенерирован ${path.relative(rootDir, llmsPath)}`);
}

12
projects/_shared/lib/run.ts Normal file
View File

@@ -0,0 +1,12 @@
import { spawnSync } from 'node:child_process';
export function run(command: string, args: string[], cwd = process.cwd()) {
const result = spawnSync(command, args, {
cwd,
stdio: 'inherit',
shell: process.platform === 'win32',
});
if (result.error) throw result.error;
if (result.status !== 0) throw new Error(`Command failed: ${[command, ...args].join(' ')}`);
}

136
projects/_shared/lib/zip.ts Normal file
View File

@@ -0,0 +1,136 @@
import fs from 'node:fs';
import path from 'node:path';
type ZipEntry = {
name: string;
content: Buffer;
};
function collectFiles(dir: string, baseDir = dir, archiveRoot = path.basename(dir)): ZipEntry[] {
return fs
.readdirSync(dir, { withFileTypes: true })
.flatMap((entry) => {
const entryPath = path.join(dir, entry.name);
if (entry.isDirectory()) return collectFiles(entryPath, baseDir, archiveRoot);
const relativePath = path.relative(baseDir, entryPath).split(path.sep).join('/');
return [
{
name: `${archiveRoot}/${relativePath}`,
content: fs.readFileSync(entryPath),
},
];
})
.sort((a, b) => a.name.localeCompare(b.name));
}
function createCrc32Table() {
return Array.from({ length: 256 }, (_, index) => {
let value = index;
for (let bit = 0; bit < 8; bit += 1) {
value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
}
return value >>> 0;
});
}
const crc32Table = createCrc32Table();
function crc32(buffer: Buffer) {
let crc = 0xffffffff;
for (const byte of buffer) {
crc = crc32Table[(crc ^ byte) & 0xff] ^ (crc >>> 8);
}
return (crc ^ 0xffffffff) >>> 0;
}
function writeUInt16(value: number) {
const buffer = Buffer.alloc(2);
buffer.writeUInt16LE(value, 0);
return buffer;
}
function writeUInt32(value: number) {
const buffer = Buffer.alloc(4);
buffer.writeUInt32LE(value >>> 0, 0);
return buffer;
}
function createZip(entries: ZipEntry[]) {
const localParts: Buffer[] = [];
const centralParts: Buffer[] = [];
const dosTime = 0;
const dosDate = ((2026 - 1980) << 9) | (1 << 5) | 1;
let offset = 0;
for (const entry of entries) {
const fileName = Buffer.from(entry.name, 'utf8');
const checksum = crc32(entry.content);
const size = entry.content.length;
const localHeader = Buffer.concat([
writeUInt32(0x04034b50),
writeUInt16(20),
writeUInt16(0),
writeUInt16(0),
writeUInt16(dosTime),
writeUInt16(dosDate),
writeUInt32(checksum),
writeUInt32(size),
writeUInt32(size),
writeUInt16(fileName.length),
writeUInt16(0),
fileName,
]);
localParts.push(localHeader, entry.content);
centralParts.push(Buffer.concat([
writeUInt32(0x02014b50),
writeUInt16(20),
writeUInt16(20),
writeUInt16(0),
writeUInt16(0),
writeUInt16(dosTime),
writeUInt16(dosDate),
writeUInt32(checksum),
writeUInt32(size),
writeUInt32(size),
writeUInt16(fileName.length),
writeUInt16(0),
writeUInt16(0),
writeUInt16(0),
writeUInt16(0),
writeUInt32(0),
writeUInt32(offset),
fileName,
]));
offset += localHeader.length + size;
}
const centralDirectory = Buffer.concat(centralParts);
const endOfCentralDirectory = Buffer.concat([
writeUInt32(0x06054b50),
writeUInt16(0),
writeUInt16(0),
writeUInt16(entries.length),
writeUInt16(entries.length),
writeUInt32(centralDirectory.length),
writeUInt32(offset),
writeUInt16(0),
]);
return Buffer.concat([...localParts, centralDirectory, endOfCentralDirectory]);
}
export function writeZipFromDirectory(sourceDir: string, zipPath: string, archiveRoot = path.basename(sourceDir)) {
fs.mkdirSync(path.dirname(zipPath), { recursive: true });
fs.writeFileSync(zipPath, createZip(collectFiles(sourceDir, sourceDir, archiveRoot)));
}

20
projects/figma-adaptive-standards/build.ts Normal file
View File

@@ -0,0 +1,20 @@
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { prepareDocs } from '../_shared/lib/prepare-docs';
import { run } from '../_shared/lib/run';
import { writeZipFromDirectory } from '../_shared/lib/zip';
import config from './project.config';
const projectDir = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(projectDir, '../..');
const docsDir = path.join(projectDir, config.docsDir);
await prepareDocs(projectDir, config);
run('npx', ['vitepress', 'build', docsDir], rootDir);
if (config.archive) {
const zipPath = path.join(rootDir, 'public', config.slug, `${config.slug}.zip`);
writeZipFromDirectory(path.join(docsDir, 'content'), zipPath, config.slug);
console.log(`Собран ${path.relative(rootDir, zipPath)}`);
}

138
projects/figma-adaptive-standards/canons/adaptive-layout-requirements.checklist.md Normal file
View File

@@ -0,0 +1,138 @@
# Чеклист приёмки макета (Figma)
> Примечание: в этом чеклисте «обоснованно» означает: по каждому «выбору» (например: `Hug/Fill/Fixed`, wrap/truncate для текста, `Fill/Fit`, `Stretch/Center`) понятно **что выбрано**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте. Если без пояснения можно понять по-разному — добавлена аннотация/комментарий.
## 0. Структура файла и нейминг
- [ ] В файле есть рабочие страницы: Cover / Overview, Design / UI, Components, Styles / Tokens, Responsive / Breakpoints, Prototype (Archive / Old — при необходимости)
- [ ] Экраны названы по единому правилу (например: `Feature / Screen — Breakpoint`)
- [ ] Компоненты названы семантически и единообразно (без «Button 1 / Button 2»)
- [ ] На странице `Responsive / Breakpoints` описаны правила перестроения для сложных зон (колонки, переносы, скрытие/появление элементов)
## 1. Брейкпоинты
- [ ] Все якорные брейкпоинты созданы в виде отдельных фреймов
- Mobile, Mobile Wide, Tablet, Laptop, Desktop (диапазоны соблюдены)
- [ ] Границы диапазонов трактуются единообразно (например: `Mobile ≤ 479`, `Mobile Wide 480–767`, `Tablet 768–1023`, `Laptop 1024–1439`, `Desktop ≥ 1440`)
- [ ] Фреймы логически и визуально связаны
- [ ] Дополнительные фреймы есть только при изменении сетки, навигации или структуры контента
## 2. Адаптивность и ресайз
- [ ] Ресайз фрейма вручную до минимального значения диапазона
- [ ] Ресайз фрейма до максимального значения диапазона
- [ ] Проверены промежуточные значения (минимум 3–5 точек внутри диапазона)
- [ ] Макет корректно меняется во всём диапазоне без создания дублирующих фреймов
- [ ] Нет коллизий при ресайзе (наезды, обрезания, неожиданные перекрытия)
- [ ] Карточки и блоки тянутся или сжимаются корректно
- [ ] Текст переносится/обрезается по правилам и не выходит за пределы контейнеров
- [ ] Навигация корректно адаптируется под ширину
## 3. Auto Layout и Constraints
- [ ] Все контейнеры, списки, карточки, кнопки, хедеры, футеры, сайдбары используют Auto Layout
- [ ] Padding задан со всех сторон через Auto Layout (без «ручных» отступов)
- [ ] Spacing между элементами задан через Auto Layout
- [ ] Режимы ресайза выбраны обоснованно (`Hug / Fill / Fixed`) для ключевых контейнеров и элементов
- [ ] При необходимости заданы min/max (для предотвращения поломок на крайних ширинах)
- [ ] Constraints заданы корректно (Left / Right / Top / Bottom / Center / Scale) там, где Auto Layout не покрывает сценарий
- [ ] Нет ручного позиционирования или абсолютных размеров без причины
## 4. Сетка / Layout Grid
- [ ] Layout Grid настроен на фреймах каждого брейкпоинта (колонки соответствуют принятому стандарту)
- [ ] Margin и gutter заданы и согласованы с версткой
- [ ] Поведение сетки выбрано обоснованно (Stretch/Center — по модели проекта)
- [ ] Основные блоки выровнены по сетке и используют согласованный шаг отступов
## 5. Компоненты
- [ ] Все повторяющиеся элементы оформлены как Components
- [ ] Используются Variants вместо копий
- [ ] Состояния компонентов показаны (минимум: Default, Hover, Active/Pressed, Disabled, Focus — если применимо)
- [ ] Компоненты корректно тянутся и меняют высоту по контенту
- [ ] Адаптивное поведение проверено во всех типовых контейнерах (экран, модалка, сайдбар, список/сетка)
## 6. Типографика
- [ ] Используются Text Styles (`H1 / H2 / Body / Caption / Button` или принятый набор)
- [ ] Используются только бесплатные шрифты (предпочтительно Google Fonts)
- [ ] Есть коллекция Variables для типографики и Modes под брейкпоинты (например: Mobile/Mobile Wide/Tablet/Laptop/Desktop — как принято в проекте)
- [ ] Text Styles используют переменные типографики (минимум размер и line-height; при необходимости letter-spacing)
- [ ] На фреймах установлен корректный Mode для соответствующего брейкпоинта
- [ ] Ограничение количества строк соблюдено там, где это критично
- [ ] Правила для текста определены: перенос или обрезка (truncate), поведение при переполнении проверено
- [ ] Проверены «экстремальные» тексты, включая одну очень длинную строку без пробелов
## 7. Цвета и стили
- [ ] Все цвета через Color Styles
- [ ] Семантические названия соблюдены (`Primary / Secondary`, `Text / Background / Border`, `Success / Error / Warning`)
- [ ] Дополнительные стили (тени/обводки/радиусы), если используются, применены единообразно
## 8. Контент и состояния UI
- [ ] Текст проверен на короткие / нормальные / длинные варианты
- [ ] Проверка переполнения и переноса строк выполнена
- [ ] Состояния UI присутствуют: Default, Hover, Active, Disabled, Focus, Loading, Empty, Error
- [ ] Для форм/инпутов показаны состояния ошибок и валидации (включая сочетания вроде `Focus + Error`, если применимо)
## 9. Изображения и медиа
- [ ] Fill / Fit задан корректно
- [ ] Safe area для обрезки изображений соблюдена
- [ ] Поддерживаются разные соотношения сторон (описано поведение при изменении ratio)
- [ ] Форматы и размеры соответствуют требованиям проекта (если есть требования к экспорту)
## 10. Навигация
- [ ] Desktop → горизонтальное меню
- [ ] Tablet → сокращённое меню
- [ ] Mobile → бургер / bottom bar
- [ ] Описаны правила overflow/сокращения (что уходит в «ещё», что скрывается/переезжает)
## 11. Accessibility (A11y)
- [ ] Контраст ≥ WCAG AA
- [ ] Минимальный размер клика 44×44 px
- [ ] Focus states проверены
- [ ] Логичный tab order соблюден
## 12. Прототипирование
- [ ] Основные пользовательские флоу представлены
- [ ] Переходы между брейкпоинтами реализованы (если требуется)
- [ ] Поведение при ресайзе проверено/продемонстрировано
## 13. Передача в разработку
- [ ] Dev Mode включён
- [ ] Все комментарии с логикой адаптивности оставлены
- [ ] Брейкпоинты, поведение блоков, скрытие/появление элементов описаны
- [ ] Ассеты к экспорту подготовлены (если требуется): корректные имена, форматы, настройки экспорта
## 14. Запрещено
- [ ] Фиксированные ширины без причины
- [ ] Дубли компонентов под каждый экран
- [ ] Текст как вектор
- [ ] Ручные отступы
- [ ] Отсутствие Auto Layout
## ✅ Итоговое решение
Макет считается **готовым к разработке**, если выполнены все пункты чеклиста и ресайз работает корректно во всех диапазонах.

473
projects/figma-adaptive-standards/canons/adaptive-layout-requirements.full.md Normal file
View File

@@ -0,0 +1,473 @@
# Требования к адаптивному дизайну в Figma (Полная версия)
Документ описывает стандарт подготовки **адаптивных** макетов в Figma так, чтобы они:
- корректно **ресайзились** в пределах заданных диапазонов ширин;
- были **предсказуемы** для разработки (верстки);
- минимизировали количество «ручных» правок и дублирования;
- содержали достаточные пояснения по поведению UI.
## Кому адресовано
- Дизайнерам интерфейсов
- Team Lead / DesignOps
- Разработчикам (для валидации качества и передачи в работу)
## Термины (коротко)
- **Брейкпоинт** — якорная ширина и набор правил компоновки, по которым интерфейс меняет структуру.
- **Диапазон** — интервал ширин, где **один** макет обязан работать корректно при ресайзе.
- **Auto Layout** — основной механизм адаптивности в Figma для контейнеров и компонентов.
- **Hug / Fill / Fixed** — режимы ресайза (по контенту / заполнять контейнер / фиксированно).
- **Constraints** — привязки объектов внутри Frame (Left/Right/Top/Bottom/Center/Scale).
- **«Обоснованно» (в контексте этого стандарта)** — по каждому «выбору» (например: `Hug/Fill/Fixed`, wrap/truncate для текста, `Fill/Fit`, `Stretch/Center`) должно быть понятно: **что именно выбрано**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте. Если выбор может трактоваться по-разному — добавьте аннотацию/комментарий на странице `Responsive / Breakpoints`.
## 1. Структура файла Figma
### 1.1. Цель структуры
Структура страниц нужна для:
- быстрого поиска актуальных экранов и компонентов;
- отделения финального UI от пояснений по адаптивности и интерактивности;
- прозрачной передачи в разработку.
### 1.2. Рекомендуемая структура страниц
- **Cover / Overview** — контекст: цель продукта, аудитория, платформы, контакты, ссылки, правила
- **Design / UI** — финальные экраны (по брейкпоинтам или по флоу)
- **Components** — библиотека компонентов и их состояния/варианты
- **Styles / Tokens** — стили: цвет, типографика, эффекты, сетки (если принято)
- **Responsive / Breakpoints** — правила поведения, схемы перестроения, примеры ресайза
- **Prototype** — интерактивные сценарии и пользовательские флоу
- **Archive / Old** — устаревшие версии (только для истории)
> Примечание: `Responsive / Breakpoints` и `Prototype` **не дублируют** финальные экраны один-в-один. Их задача — объяснить поведение, которое не очевидно из статичных макетов.
### 1.3. Правила нейминга (минимальный стандарт)
- Страницы: `Design / UI`, `Components` и т.д. — одинаково во всех проектах.
- Фреймы экранов: `Feature / Screen — Breakpoint` (например: `Catalog / List — Desktop`)
- Компоненты: `ComponentName` + группа (`Button / Primary`, `Input / TextField`), семантика важнее внешнего вида.
### 1.4. Что считается «готовым набором» в файле
В файле должны быть:
- фреймы всех якорных брейкпоинтов;
- компоненты и их состояния (через Variants);
- стили (цвета/типографика) с семантическими именами;
- пояснения по адаптивности и «порогам» изменений.
## 2. Брейкпоинты и адаптивность
### 2.1. Якорные брейкпоинты (база)
| Версия | Размер макета (Frame) | Диапазон ресайза |
|-------------|----------------|---------------|
| Mobile | 375 px | 360 – 479 px |
| Mobile Wide | 560 px | 480 – 767 px |
| Tablet | 992 px | 768 – 1023 px |
| Laptop | 1280 px | 1024 – 1439 px|
| Desktop | 1640 px | 1440 – 1920 px|
Требования:
- Каждый брейкпоинт — отдельный **Frame** (Screen Frame).
- Диапазоны рассматриваются как **интервалы ресайза**: макет должен работать от min до max.
- Все брейкпоинты должны быть **логически и визуально связаны**: типографика, сетка, шаги отступов и компоненты должны «эволюционировать», а не пересобираться хаотично.
> Примечание про границы: диапазоны заданы без пересечений. Пороговые значения: 480/768/1024/1440. Пример правила: `Mobile ≤ 479`, `Mobile Wide 480–767`, `Tablet 768–1023`, `Laptop 1024–1439`, `Desktop ≥ 1440`.
### 2.2. Когда допустимо менять список брейкпоинтов
Базовый набор можно корректировать **только** при объективной необходимости:
- меняется **навигационный паттерн** (например, горизонтальное меню → бургер);
- меняется **сетка** (количество колонок/маржины/контейнер);
- меняется **иерархия контента** (скрытие/появление блока, перестановка основных зон);
- появляются «скачки» из-за контента, которые нельзя закрыть корректным ресайзом.
Недопустимая причина:
- «так удобнее рисовать» или «не получилось настроить авто-лейаут». В этом случае исправляется настройка, а не множатся фреймы.
### 2.3. Принцип «один фрейм — один диапазон»
Один фрейм описывает **поведение интерфейса в диапазоне**, а не конкретное устройство.
Дополнительный фрейм внутри диапазона создаётся только если:
- на определённой ширине меняется **структура** (например, 2 колонки → 3 колонки);
- меняется **тип навигации**;
- меняется **композиция** ключевых зон (например, фильтры из сайдбара уходят в drawer).
### 2.4. Обязательное требование: корректный ресайз
Макет считается адаптивным только если он корректно ресайзится вручную **во всём диапазоне**.
Проверка (обязательная):
- вручную измените ширину фрейма до **минимума** диапазона;
- вручную измените ширину фрейма до **максимума** диапазона;
- проверьте промежуточные значения (минимум 3–5 точек внутри диапазона).
Оценивается:
- поведение сетки и контейнеров;
- перенос и переполнение текста;
- колонки, карточки и списки;
- навигация и хедер/футер;
- отсутствие коллизий: наездов, обрезаний, неожиданных перекрытий;
- сохранение визуальной иерархии.
> Макет некорректен, если «работает» только на базовой ширине, а при ресайзе ломается.
### 2.5. Реализация адаптивности в Figma (обязательные правила)
#### 2.5.1. Auto Layout
Обязателен для:
- всех контейнеров списков и лент;
- карточек, таблиц, форм;
- хедера/футера/сайдбара;
- любых повторяющихся групп (где есть паддинги и расстояния).
Минимальные требования к Auto Layout:
- паддинги задаются через Auto Layout (а не «ручными» прямоугольниками);
- расстояния между элементами задаются через `Spacing`;
- направление (Horizontal/Vertical) и `Wrap` выбираются обоснованно;
- в ключевых местах задаются **min/max** (если без этого появляются «переломы» компоновки).
#### 2.5.2. Resizing: Hug / Fill / Fixed
Правила выбора:
- **Контейнеры** (строки, колонки, секции) чаще всего: `Fill container` по ширине.
- **Элементы по контенту** (лейблы, чипсы, иконки): `Hug contents`.
- **Фиксированные размеры** — только для:
- иконок (например, 16/20/24);
- интерактивных областей, где фикс диктуется UX (например, высота кнопки);
- медиа с заданным форм-фактором (но с контролем кропа).
Типичная ошибка: «всё Fixed». Это убивает адаптивность.
#### 2.5.3. Constraints
Constraints применяются там, где Auto Layout не покрывает сценарий (например, декоративные элементы, фоновые иллюстрации, абсолютные позиционирования).
Минимальные правила:
- элемент, который должен «прилипать» к краю контейнера, получает соответствующие привязки (`Left/Right/Top/Bottom`);
- элементы, которые должны масштабироваться пропорционально, используют `Scale` только если это оправдано (иначе деформируется типографика и иконки);
- избегайте смешения: Auto Layout внутри контейнера + хаотичные constraints у детей.
### 2.6. Примеры адаптивного поведения (как описывать)
В странице `Responsive / Breakpoints` для каждой сложной зоны должны быть описаны правила в формате:
- **Что фиксировано** (например, высота хедера 64px)
- **Что тянется** (контейнер контента по ширине)
- **Что переносится/перестраивается** (карточки wrap, 1→2→3 колонки)
- **Что скрывается/появляется** (например, вторичный CTA скрывается на mobile)
Пример описания (текстом):
- «Сетка карточек: на Mobile — 1 колонка, на Tablet — 2 колонки, на Laptop/ Desktop — 3 колонки. Карточка имеет min-width 280px, при нехватке места переносится на новую строку (wrap).»
## 3. Компоненты
### 3.1. Что обязано быть компонентом
Компонентами должны быть оформлены:
- любые повторяющиеся UI-элементы (кнопки, поля, карточки, бейджи, таблицы, модалки);
- сложные блоки, встречающиеся минимум 2 раза;
- элементы с состояниями/интерактивностью.
Запрещено:
- копировать элементы «вручную» вместо компонентов;
- создавать отдельные компоненты под каждый брейкпоинт, если поведение можно решить ресайзом.
### 3.2. Variants вместо копий
Состояния и вариации должны быть в **Variants**.
Минимальный набор состояний (если применимо):
- `Default`, `Hover`, `Pressed/Active`, `Disabled`, `Focus`.
Дополнительные состояния по необходимости:
- `Loading`, `Error`, `Success`, `Empty`.
### 3.3. Требования к адаптивности компонентов
Компонент считается адаптивным, если:
- корректно меняет ширину при `Fill` (когда вставлен в растягиваемый контейнер);
- корректно меняет высоту при изменении контента (например, многострочный текст);
- не ломает паддинги и расстояния при ресайзе;
- корректно работает внутри разных контейнеров (list/grid, modal, sidebar).
Обязательная проверка:
- вставьте компонент в контейнер разной ширины и измените ширину родителя;
- проверьте состояния и длину текста.
### 3.4. Типовые требования по компонентам (примерно, без привязки к бренду)
- **Button**: фиксированная высота (например, 40/44/48 по дизайн-системе), ширина `Hug` или `Fill` по контексту, текст не должен вылезать (правила: перенос/обрезка задаются обоснованно).
- **Input**: высота фиксирована, поле `Fill`, лейбл и хелпер-текст — `Hug` с переносом.
- **Card**: контейнер `Fill`, текстовые блоки — `Hug` по высоте, изображение — обоснованный `Fill/Fit` с safe-area.
## 4. Сетка / Layout Grid
### 4.1. Зачем нужна сетка
Сетка задаёт предсказуемую структуру для:
- выравнивания и ритма;
- повторяемости решений;
- соответствия верстке.
### 4.2. Базовая рекомендация по колонкам
| Device | Колонки |
|---------|---------|
| Mobile | 4 |
| Tablet | 8 |
| Desktop | 12 |
Примечания:
- `Laptop` обычно использует 12 колонок (как Desktop), но может отличаться маржинами.
- Внутренний контейнер (max-width) допускается, если продукт предполагает «центрированный контент».
### 4.3. Настройки (что должно быть задано)
Для каждого фрейма должны быть явно определены:
- `margin` (внешние поля);
- `gutter` (межколоночные расстояния);
- поведение сетки (`Stretch`/`Center`) — в зависимости от выбранной модели.
Требование:
- сетка в Figma должна **соответствовать** принятой сетке в верстке (или быть согласована до начала дизайна).
### 4.4. Пример логики перестроения с сеткой
- На Mobile: контент в 4 колонки, карточки занимают 4/4.
- На Tablet: 8 колонок, карточки 4/8 (2 колонки на ряд).
- На Desktop: 12 колонок, карточки 4/12 (3 колонки на ряд).
---
## 5. Типографика
### 5.1. Text Styles + Variables (обязательное правило)
Все текстовые слои в макете обязаны использовать **Text Styles**.
Text Styles должны быть **семантическими** (а не «по экрану») и опираться на **типографические токены в Variables**.
Минимальный набор (пример семантики):
- `H1`, `H2`, `H3`
- `Body / Regular`, `Body / Medium`
- `Caption`
- `Button`
Требования:
- одинаковая семантика должна выглядеть согласованно во всех экранах;
- локальные «ручные» правки размеров/интервалов поверх стиля недопустимы (кроме редких исключений, зафиксированных правилом);
- разрешены только бесплатные шрифты; предпочтительно использовать **Google Fonts**;
- значения типографики (минимум `font-size` и `line-height`, при необходимости `letter-spacing`) — источник правды в **Variables**;
- адаптация типографики между брейкпоинтами делается через **Modes** в Variables, а не через дублирование текстовых стилей «под каждый брейкпоинт».
### 5.2. Адаптация типографики между брейкпоинтами через Modes
Если типографика меняется между брейкпоинтами, это изменение фиксируется **через Modes** в коллекции Variables.
Обязательная структура:
- есть коллекция Variables для типографики (например: `Typography`);
- в коллекции заведены Modes под брейкпоинты (например: `Mobile`, `Mobile Wide`, `Tablet`, `Laptop`, `Desktop` — в точности как принято в проекте);
- для каждого семантического стиля (`H1/H2/Body/...`) определены переменные минимум для:
- `font-size`;
- `line-height`;
- опционально: `letter-spacing` (редко и только обоснованно).
Обязательное правило применения:
- Text Styles используют эти переменные как значения типографики;
- у каждого фрейма экрана выставлен корректный Mode (Mobile/Mobile Wide/Tablet/Laptop/Desktop), чтобы типографика внутри фрейма соответствовала брейкпоинту;
- любые отличия от токенов (если они вообще допускаются) должны быть подписаны: **что изменено**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте.
### 5.3. Многострочный текст: переносы и ограничения
Для ключевых текстовых блоков обязаны быть определены правила:
- переносится ли текст (wrap) или обрезается (truncate);
- сколько максимум строк допустимо в конкретном контексте (карточка/ячейка/таблица/заголовок/кнопка);
- что происходит при переполнении (например, `…`, перенос на следующую строку, увеличение высоты блока — что именно ожидается в UI).
Минимальная проверка контента:
- короткий текст;
- нормальный (ожидаемый);
- длинный;
- «экстремальный» (очень длинный) — для выявления поломок;
- одна очень длинная строка без пробелов (проверка на разъезд/переполнение в узких контейнерах).
## 6. Цвета и стили
### 6.1. Цвета — только через Color Styles
Все цвета должны быть оформлены как **Color Styles**.
Требование по именованию:
- семантика важнее оттенка.
Пример семантических групп:
- `Primary / Secondary`
- `Text / Background / Border`
- `Success / Error / Warning`
### 6.2. Дополнительные стили
Если в проекте используются:
- тени,
- блюр,
- обводки,
- радиусы,
то они должны быть единообразны и по возможности вынесены в стили/токены (в рамках принятых процессов команды).
## 7. Контент и состояния UI
### 7.1. Контентные сценарии
Для каждого экрана/секции, где возможны вариации, должны быть проверены:
- короткий/длинный текст;
- пустые значения;
- максимальные значения (например, большие числа);
- локализация (если продукт многоязычный) — хотя бы проверка длины.
### 7.2. Состояния UI (обязательный список)
В зависимости от компонента/экрана должны быть представлены состояния:
- `Default`
- `Hover`
- `Active/Pressed`
- `Disabled`
- `Focus`
- `Loading`
- `Empty`
- `Error`
Требование:
- состояния должны быть реализованы либо в Variants компонентов, либо как отдельные фреймы/слои с явной маркировкой.
### 7.3. Ошибки и валидация
Где есть ввод и формы, необходимо:
- указать правила отображения ошибок (текст, цвет, иконка, границы);
- учесть переполнение текста ошибки;
- показать состояние `Error` и `Focus` одновременно, если применимо.
## 8. Изображения и медиа
### 8.1. Обоснованный выбор Fill / Fit
- `Fill` (cover) используется, когда допустима обрезка.
- `Fit` (contain) используется, когда обрезка недопустима.
### 8.2. Safe area для обрезки
Если используется `Fill`, у изображений должна быть предусмотрена **безопасная зона** (safe area):
- важные объекты (лицо, логотип, текст на фото) не должны попадать под обрезку при изменении пропорций.
### 8.3. Разные соотношения сторон
Требование:
- если контент может приходить с разными ratio, дизайн обязан описать поведение:
- фиксируем ли высоту блока;
- разрешаем ли менять высоту по контенту;
- используем ли placeholder/фон.
## 9. Навигация
### 9.1. Паттерны по брейкпоинтам (базово)
- Desktop → горизонтальное меню
- Tablet → сокращённое меню (или гибрид)
- Mobile → бургер / bottom bar
### 9.2. Требования к адаптивности навигации
- при уменьшении ширины не должно происходить «переполнения» пунктов меню;
- должны быть определены правила:
- что уходит в «ещё»/overflow;
- когда включается бургер;
- как ведут себя вторичные действия.
### 9.3. Сложные случаи
Если навигация включает:
- табы,
- фильтры,
- хлебные крошки,
то должно быть описано поведение на узких ширинах (скролл, перенос, сокращение, скрытие).
## 10. Accessibility (A11y)
### 10.1. Контраст
Требование:
- контраст текста и интерактивных элементов должен быть не ниже **WCAG AA** (если продуктом не задан иной стандарт).
### 10.2. Размер клика (hit area)
Требование:
- минимальная интерактивная зона: **44×44 px**.
### 10.3. Focus states и порядок
Обязательно:
- состояние `Focus` для интерактивных элементов;
- логичный `tab order` (особенно в формах и диалогах).
## 11. Прототипирование
### 11.1. Что обязательно прототипировать
- основные пользовательские флоу (критические пути);
- ключевые состояния (ошибка/пусто/загрузка) — если важны для сценария;
- диалоги, drawer, dropdown — если это влияет на понимание поведения.
### 11.2. Переходы между брейкпоинтами
Если в продукте предполагается использование интерфейса в разных ширинах (веб), необходимо:
- зафиксировать, как ведёт себя интерфейс при переходе через пороги (например, при ресайзе окна).
### 11.3. Проверка поведения при ресайзе
В прототипе или на странице `Responsive / Breakpoints` необходимо продемонстрировать:
- как перестраиваются блоки;
- что скрывается/появляется;
- где меняется навигационный паттерн.
## 12. QA и проверка адаптивности
### 12.1. Обязательный сценарий проверки
1) Ресайз фрейма вручную до min диапазона.
2) Ресайз до max диапазона.
3) Проверка промежуточных значений.
4) Проверка отдельных компонентов (в изоляции).
5) Проверка экстремальных контентных значений.
### 12.2. Типовые ошибки (что искать)
- текст выходит за границы;
- кнопки/поля «схлопываются» ниже допустимого;
- пропадает сеточный ритм;
- карточки ломают высоту соседей непредсказуемо;
- элементы перекрывают друг друга при ресайзе;
- компоненты не тянутся, потому что внутри `Fixed` вместо `Fill/Hug`.
## 13. Передача разработчику
### 13.1. Dev Mode
Требование:
- Dev Mode включён и доступен;
- структуры слоёв достаточно для инспекта (без лишнего мусора и без превращения текста в вектор).
### 13.2. Комментарии и пояснения
Должны быть комментарии/аннотации по:
- брейкпоинтам и порогам изменений;
- правилам скрытия/появления блоков;
- нестандартным случаям (например, «на 1024 фильтры переезжают в drawer»).
### 13.3. Экспорт ассетов
Если требуется экспорт:
- указать форматы и размеры;
- убедиться, что иконки/иллюстрации подготовлены корректно (без лишних слоёв, с понятными именами).
## 14. Запрещено
- фиксированные ширины без причины (если элемент обязан тянуться);
- дубли компонентов под каждый экран вместо нормального ресайза;
- текст как вектор;
- «ручные» отступы вместо Auto Layout;
- отсутствие Auto Layout там, где есть паддинги/списки/повторяемые структуры.
## 15. Минимальный стандарт качества (acceptance criteria)
Макет считается адаптивным и готовым к разработке, если:
1. Корректно ресайзится во всём диапазоне каждого брейкпоинта.
2. Использует Auto Layout + корректные Resizing (Hug/Fill/Fixed) и Constraints.
3. Имеет якорные брейкпоинты, а дополнительные фреймы появляются только при структурных изменениях.
4. Компоненты оформлены как Components с Variants, состояния UI показаны.
5. Понятен разработчику без дополнительных «устных» пояснений: правила адаптивности описаны в файле.

156
projects/figma-adaptive-standards/canons/adaptive-layout-requirements.short.md Normal file
View File

@@ -0,0 +1,156 @@
# Требования к адаптивному дизайну в Figma (Сжатая версия)
> Примечание: в этом документе «обоснованно» означает: по каждому «выбору» (например: `Hug/Fill/Fixed`, wrap/truncate для текста, `Fill/Fit`) понятно **что выбрано**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте.
## 1. Структура файла Figma
Рекомендуемая структура:
- **Cover / Overview** — описание проекта, цели, контакты, ссылки
- **Design / UI** — финальные экраны
- **Components** — повторяющиеся элементы и Variants
- **Styles / Tokens** — цвета, типографика, эффекты
- **Responsive / Breakpoints** — логика адаптивного поведения
- **Prototype** — интерактивные сценарии и флоу
- **Archive / Old** — устаревшие версии
> Примечание: Страницы `Responsive / Breakpoints` и `Prototype` не дублируют дизайн-экраны, служат для объяснения поведения интерфейса и интерактивности.
## 2. Брейкпоинты и адаптивность
### 2.1. Якорные брейкпоинты
| Версия | Размер макета (Frame) | Диапазон (CSS px) |
|---------------|----------------|-------------------|
| Mobile | 375 px | 360 – 479 px |
| Mobile Wide | 560 px | 480 – 767 px |
| Tablet | 992 px | 768 – 1023 px |
| Laptop | 1280 px | 1024 – 1439 px |
| Desktop | 1640 px | 1440 – 1920 px |
- Каждый брейкпоинт — отдельный Frame в Figma.
- Количество брейкпоинтов **может корректироваться** (визуальная иерархия, контент, сетка, навигация).
- Все брейкпоинты должны быть **логически и визуально связаны**.
### 2.2. Принцип «один фрейм — один диапазон»
- Один фрейм описывает **диапазон ширин**, а не отдельное устройство.
- Дополнительный фрейм — только при изменении сетки, навигации или структуры контента.
### 2.3. Обязательное требование к ресайзу
- Макеты должны **корректно ресайзиться во всём диапазоне**, без дополнительных фреймов.
- Проверяется:
- изменение ширины фрейма вручную до min/max диапазона
- поведение сетки, карточек, текста, навигации
- отсутствие коллизий и переполнений
- сохранение визуальной иерархии
> Макет некорректен, если работает только на базовой ширине.
### 2.4. Реализация в Figma
- **Обязательно:** Auto Layout на всех контейнерах, обоснованный выбор `Hug / Fill / Fixed`, Constraints, min/max width для ключевых блоков.
- **Запрещено:** ручное позиционирование без Auto Layout, абсолютные размеры без необходимости, дубли фреймов для адаптивности.
## 3. Компоненты
- Все повторяющиеся элементы — **Components**; использовать **Variants** вместо копий.
- Адаптивность компонентов:
- тянутся по ширине
- меняют высоту по контенту
- корректно ведут себя в разных контейнерах
## 4. Сетка / Layout Grid
| Device | Колонки |
|---------|---------|
| Mobile | 4 |
| Tablet | 8 |
| Desktop | 12 |
- Настройки: margin, gutter, column width
- Сетка должна соответствовать верстке
## 5. Типографика
- Только через **Text Styles** (семантика: `H1 / H2 / Body / Caption / Button`)
- Только бесплатные шрифты (предпочтительно **Google Fonts**)
- Значения типографики (минимум размер и line-height) — через **Variables**
- Адаптация между брейкпоинтами — через **Modes** в Variables (Mobile/Mobile Wide/Tablet/Laptop/Desktop)
- Для ключевых текстов определены правила: wrap/truncate и max lines
## 6. Цвета и стили
- **Color Styles** с семантическими названиями:
`Primary / Secondary`, `Text / Background / Border`, `Success / Error / Warning`
## 7. Контент и состояния UI
- Текст: короткий / нормальный / длинный, проверка переполнения
- Состояния UI: Default, Hover, Active, Disabled, Focus, Loading, Empty, Error
## 8. Изображения и медиа
- Использовать `Fill / Fit` обоснованно
- Safe area для обрезки
- Поддержка разных соотношений сторон
- Форматы и размеры соответствуют проекту
## 9. Навигация
- Desktop → горизонтальное меню
- Tablet → сокращённое меню
- Mobile → бургер / bottom bar
## 10. Accessibility (A11y)
- Контраст ≥ WCAG AA
- Минимальный размер клика: 44×44 px
- Focus states, логичный tab order
## 11. Прототипирование
- Основные пользовательские флоу
- Переходы между брейкпоинтами
- Проверка поведения при ресайзе
## 12. QA и проверка адаптивности
- Ресайз фрейма вручную до min/max диапазона
- Проверка компонентов отдельно
- Проверка экстремальных значений
- Макет готов, если ресайз работает корректно во всём диапазоне и нет коллизий
## 13. Передача разработчику
- Dev Mode включён
- Комментарии с логикой адаптивности
- Описаны брейкпоинты, поведение блоков, скрытие/появление элементов
## 14. Запрещено
- Фиксированные ширины без причины
- Дубли компонентов под каждый экран
- Текст как вектор
- Ручные отступы
- Отсутствие Auto Layout
## 15. Минимальный стандарт качества
Макет считается адаптивным, если:
1. Корректно ресайзится во всём диапазоне
2. Использует Auto Layout + Constraints
3. Имеет брейкпоинты
4. Понятен разработчику без дополнительных объяснений

30
projects/figma-adaptive-standards/canons/index.md Normal file
View File

@@ -0,0 +1,30 @@
title: Figma Adaptive Standards
description: Карта стандартов подготовки адаптивных макетов в Figma для передачи в разработку
# Figma Adaptive Standards
Figma Adaptive Standards — набор требований к подготовке адаптивных макетов в Figma. Документация фиксирует, как описывать брейкпоинты, проверять ресайз в диапазоне, настраивать Auto Layout и Constraints, оформлять компоненты, сетки, типографику, состояния интерфейса, A11y и передачу в разработку.
Стандарты нужны, чтобы макет был не только визуальной картинкой на нескольких ширинах, а рабочей моделью поведения интерфейса. По документам должно быть понятно, как экран живёт между брейкпоинтами, какие элементы тянутся, какие перестраиваются, что происходит с длинным контентом и где дизайнерское решение требует отдельного пояснения.
## Для кого
- **Дизайнерам** — как чеклист качества адаптивного макета перед передачей в разработку.
- **Разработчикам** — как источник правил для проверки реализуемости макета и уточнения спорных мест.
- **Team Lead / DesignOps** — как единый стандарт приёмки дизайн-файлов и согласования процесса.
## Разделы
- [Сжатая версия](/adaptive-layout-requirements/short) — короткий набор требований для быстрого применения в проекте.
- [Полная версия](/adaptive-layout-requirements/full) — развёрнутое описание правил, терминов, проверок и типовых решений.
- [Чеклист приёмки](/adaptive-layout-requirements/checklist) — практический список проверок перед передачей макета в разработку.
## Как читать
Начните со сжатой версии, чтобы понять общий стандарт. Затем используйте полную версию как справочник по спорным вопросам: брейкпоинтам, ресайзу, Auto Layout, компонентам, сетке, типографике и состояниям UI. Перед передачей макета в разработку пройдите чеклист приёмки.
## Главный принцип
Адаптивный макет считается готовым не тогда, когда нарисованы несколько статичных фреймов, а когда понятна логика поведения интерфейса во всём диапазоне ширин: от минимального значения до максимального, с длинным контентом, разными состояниями и предсказуемой передачей в разработку.

27
projects/figma-adaptive-standards/docs/.vitepress/config.ts Normal file
View File

@@ -0,0 +1,27 @@
import { defineConfig } from 'vitepress';
import taskLists from 'markdown-it-task-lists';
import llmstxt from 'vitepress-plugin-llms';
import { themeSyncHead } from '../../../_shared/docs/vitepress/themeHead';
import { sidebar, site } from '../docs.config';
export default defineConfig({
title: site.title,
description: site.description,
base: site.base,
outDir: site.outDir,
srcDir: 'content',
cleanUrls: true,
head: [...themeSyncHead],
vite: {
plugins: [llmstxt()],
},
markdown: {
config(md) {
md.use(taskLists);
},
},
themeConfig: {
sidebar,
socialLinks: [],
},
});

1
projects/figma-adaptive-standards/docs/.vitepress/theme/index.ts Normal file
View File

@@ -0,0 +1 @@
export { default } from '../../../../_shared/docs/vitepress/theme';

33
projects/figma-adaptive-standards/docs/docs.config.ts Normal file
View File

@@ -0,0 +1,33 @@
export const site = {
title: 'Figma Adaptive Standards',
description: 'Стандарты подготовки адаптивных макетов в Figma',
base: '/figma-adaptive-standards/',
outDir: '../../../public/figma-adaptive-standards',
};
/**
* Карта монтирования исходных канонов в VitePress-документацию.
*
* `source` указывает на markdown-файл внутри `canons/`.
* `target` задаёт путь, по которому этот файл попадёт в `docs/content/`
* и станет страницей итоговой документации.
*/
export const mounts = [
{ target: 'index.md', source: 'canons/index.md' },
{ target: 'overview.md', source: 'canons/index.md' },
{ target: 'adaptive-layout-requirements/short.md', source: 'canons/adaptive-layout-requirements.short.md' },
{ target: 'adaptive-layout-requirements/full.md', source: 'canons/adaptive-layout-requirements.full.md' },
{ target: 'adaptive-layout-requirements/checklist.md', source: 'canons/adaptive-layout-requirements.checklist.md' },
];
export const sidebar = [
{
text: 'Стандарты',
items: [
{ text: 'Обзор', link: '/overview' },
{ text: 'Сжатая версия', link: '/adaptive-layout-requirements/short' },
{ text: 'Полная версия', link: '/adaptive-layout-requirements/full' },
{ text: 'Чеклист приёмки', link: '/adaptive-layout-requirements/checklist' },
],
},
];

5
projects/figma-adaptive-standards/project.config.ts Normal file
View File

@@ -0,0 +1,5 @@
export default {
slug: 'figma-adaptive-standards',
docsDir: 'docs',
archive: true,
} as const;

0
projects/figma-adaptive-standards/scripts/.gitkeep Normal file
View File

20
projects/nextjs-style-guide/build.ts Normal file
View File

@@ -0,0 +1,20 @@
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { prepareDocs } from '../_shared/lib/prepare-docs';
import { run } from '../_shared/lib/run';
import { writeZipFromDirectory } from '../_shared/lib/zip';
import config from './project.config';
const projectDir = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(projectDir, '../..');
const docsDir = path.join(projectDir, config.docsDir);
await prepareDocs(projectDir, config);
run('npx', ['vitepress', 'build', docsDir], rootDir);
if (config.archive) {
const zipPath = path.join(rootDir, 'public', config.slug, `${config.slug}.zip`);
writeZipFromDirectory(path.join(docsDir, 'content'), zipPath, config.slug);
console.log(`Собран ${path.relative(rootDir, zipPath)}`);
}

103
projects/nextjs-style-guide/canons/DEVELOP.md Normal file
View File

@@ -0,0 +1,103 @@
---
title: Гид для агента
description: Что AI-агент обязан прочитать перед началом работы, а что — по задаче.
---
# Обязательное чтение перед началом работы
Этот документ определяет **строгий порядок действий агента перед выполнением любых задач**.
## Общее правило
Перед началом работы над **любой задачей** агент **обязан ознакомиться с базовой документацией проекта**.
Нарушение этого порядка считается ошибкой.
---
## Порядок обязательного чтения
Агент должен читать документацию **строго в следующем порядке**:
### 1. Архитектура (КРИТИЧЕСКИ ВАЖНО)
* [Архитектура: Обзор](./basics/architecture/index.md)
* [Архитектура: Слои](./basics/architecture/layers.md)
* [Архитектура: Модули](./basics/architecture/modules.md)
* [Архитектура: Сегменты](./basics/architecture/segments.md)
**Архитектура — это самое важное в проекте.**
Агент обязан:
* строго понимать архитектурный подход (SLM)
* соблюдать архитектуру **на 100% без отклонений**
* не предлагать решений, нарушающих архитектурные принципы
* не упрощать архитектуру даже ради скорости выполнения задачи
Любое нарушение архитектуры недопустимо.
---
### 2. Базовые правила
После архитектуры необходимо изучить:
* [Технологии и библиотеки](./basics/tech-stack.md)
* [Именование](./basics/naming.md)
* [Стиль кода](./basics/code-style.md)
* [Документирование](./basics/documentation.md)
* [Типизация](./basics/typing.md)
Агент обязан применять эти правила во всех решениях.
---
## Использование карты документации
Для поиска дополнительных сведений агент должен использовать:
* [MAP.md](./MAP.md)
MAP.md содержит ссылки на все прикладные и вспомогательные разделы.
Агент может:
* переходить к нужным разделам через MAP.md
* уточнять детали реализации
* искать примеры и частные случаи
---
## Запрещено
Агенту запрещено:
* начинать выполнение задачи без изучения архитектуры
* игнорировать базовые правила
* принимать решения, противоречащие архитектуре
* придумывать собственные подходы, если они не описаны в документации
---
## Ожидаемое поведение агента
Перед выполнением задачи агент должен:
1. Изучить архитектуру
2. Изучить базовые правила
3. При необходимости открыть MAP.md и найти релевантные разделы
4. Только после этого приступать к решению задачи
---
## Приоритеты
При принятии решений агент должен руководствоваться следующим приоритетом:
1. **Архитектура**
2. Базовые правила
3. Документация из MAP.md
4. Задача пользователя
Если задача противоречит архитектуре — задача должна быть переосмыслена, а не выполнена напрямую.

59
projects/nextjs-style-guide/canons/MAP.md Normal file
View File

@@ -0,0 +1,59 @@
# Карта документации
Список всех разделов архива с относительными ссылками. Точка входа
— `DEVELOP.md` рядом с этим файлом.
## Подсказки
- [Подсказки](./workflow.md) — Короткие ответы на типовые вопросы и решения для спорных ситуаций.
## Базовые правила
- [Технологии и библиотеки](./basics/tech-stack.md) — Какие библиотеки и инструменты используются в проекте.
- [Именование](./basics/naming.md) — Как называть переменные, файлы и прочие сущности в коде.
- [Архитектура: Обзор](./basics/architecture/index.md) — Архитектурный подход проекта: что такое SLM и как он устроен.
- [Архитектура: Слои](./basics/architecture/layers.md) — Из каких слоёв состоит SLM-архитектура и как они связаны.
- [Архитектура: Модули](./basics/architecture/modules.md) — Что такое модуль в SLM-архитектуре и как он устроен.
- [Архитектура: Сегменты](./basics/architecture/segments.md) — Что такое сегмент модуля в SLM-архитектуре и какие они бывают.
- [Стиль кода](./basics/code-style.md) — Как оформляется код в проекте.
- [Документирование](./basics/documentation.md) — Что и как документировать в коде.
- [Типизация](./basics/typing.md) — Как типизируется код в проекте.
## Прикладные разделы
- [Создание проекта: Из шаблона](./applied/creating-project/from-template.md) — Создание нового проекта на основе готового шаблона.
- [Создание проекта: По гайду вручную](./applied/creating-project/manual.md) — Поэтапное создание нового проекта без использования шаблона.
- [Создание проекта: Чистый Next.js](./applied/creating-project/nextjs.md) — Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
- [Структура проекта](./applied/project-structure.md) — Из чего состоит проект и где что лежит.
- [Страницы](./applied/page-level.md) — Как работать со страницами и другими файлами роутинга Next.js App Router.
- [Компонент](./applied/component.md) — Как создавать React-компоненты внутри SLM-модулей.
- [Модуль](./applied/module.md) — Как создавать и организовывать SLM-модули в проекте.
- [REST-клиент](./applied/rest-client/index.md) — Настройка REST-клиента сервиса для работы с внешним API.
- [REST-клиент: Настройка REST-клиента](./applied/rest-client/setup/index.md) — Из чего состоит REST-клиент и что подготовить перед использованием API.
- [REST-клиент: Автогенерация REST-клиента](./applied/rest-client/setup/auto.md) — Генерация REST-клиента из OpenAPI-спецификации.
- [REST-клиент: Ручное создание REST-клиента](./applied/rest-client/setup/manual.md) — Создание REST-клиента вручную, когда OpenAPI нет или он неполный.
- [REST-клиент: GET-хуки REST-клиента](./applied/rest-client/setup/hooks.md) — Прозрачные SWR-обёртки над GET-методами REST-клиента.
- [REST-клиент: Использование REST-клиента](./applied/rest-client/usage.md) — Как вызывать готовый REST-клиент в серверном коде и submit-функциях.
- [Получение данных](./applied/data-fetch/index.md) — Как получать данные с учётом рендера страницы.
- [Получение данных: Серверный await](./applied/data-fetch/server-await.md) — Получение REST-данных на сервере до первого HTML.
- [Получение данных: Параллельные серверные запросы](./applied/data-fetch/parallel-server-requests.md) — Как запускать независимые REST-запросы на сервере без waterfall.
- [Получение данных: Передача промиса ниже](./applied/data-fetch/pass-promise-down.md) — Как запускать серверный REST-запрос выше и ожидать его во вложенном server-компоненте.
- [Получение данных: Начальные данные для клиентских хуков](./applied/data-fetch/client-hooks-initial-data.md) — Как дать клиентским GET-хукам начальные REST-данные.
- [Получение данных: Клиентский GET-хук](./applied/data-fetch/client-get-hook.md) — Получение REST-данных в Client Components через готовые GET-хуки REST-клиента.
- [Получение данных: Business-композиция](./applied/data-fetch/business-composition.md) — Когда REST-данные нужно объединить или интерпретировать в бизнес-модуле.
- [Стили: Настройка](./applied/styles/styles-setup.md) — Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
- [Стили: Использование](./applied/styles/styles-usage.md) — Как пишутся стили в проекте.
- [SVG-спрайты](./applied/svg-sprites/svg-sprites-intro.md) — Что такое SVG-спрайты и какие проблемы они решают.
- [SVG-спрайты: Настройка](./applied/svg-sprites/svg-sprites-setup.md) — Подключение SVG-спрайтов в новом проекте.
- [SVG-спрайты: Использование](./applied/svg-sprites/svg-sprites-usage.md) — Как добавлять и использовать SVG-иконки в коде.
- [Изображения](./applied/images.md) — Как подключать изображения через Next.js Image в проекте.
- [Шрифты](./applied/fonts.md) — Как подключать шрифты через Next.js Font в проекте.
- [Алиасы импортов](./applied/aliases.md) — Какие алиасы импортов есть в проекте и как ими пользоваться.
- [Шаблоны генерации](./applied/templates/templates-intro.md) — Что такое шаблоны кодогенерации и какие проблемы они решают.
- [Шаблоны генерации: Настройка](./applied/templates/templates-setup.md) — Первичная установка шаблонов кодогенерации в проект.
- [Шаблоны генерации: Создание шаблонов](./applied/templates/templates-create.md) — Структура шаблонов, синтаксис переменных и примеры.
- [Шаблоны генерации: Использование](./applied/templates/templates-usage.md) — Генерация файлов из шаблонов через VS Code плагин и CLI.
- [Biome](./applied/biome.md) — Установка и настройка линтера-форматтера в новом проекте.
- [PostCSS](./applied/postcss.md) — Установка и настройка CSS-процессора в новом проекте.
- [VS Code](./applied/vscode.md) — Единые настройки редактора и расширений для команды.
- [Локализация](./applied/localization.md) — Как организовать локализацию как infra-модуль.

77
projects/nextjs-style-guide/canons/applied/aliases.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: Алиасы импортов
description: Какие алиасы импортов есть в проекте и как ими пользоваться.
keywords: [алиасы, aliases, paths, tsconfig, импорты, baseUrl, app, layouts, screens, widgets, business, infra, ui, shared]
---
# Алиасы импортов
Какие алиасы импортов есть в проекте и как ими пользоваться.
## Конфиг
`tsconfig.json` в корне проекта:
```json
{
"compilerOptions": {
"paths": {
"app/*": ["./src/app/*"],
"layouts/*": ["./src/layouts/*"],
"screens/*": ["./src/screens/*"],
"widgets/*": ["./src/widgets/*"],
"business/*": ["./src/business/*"],
"infra/*": ["./src/infra/*"],
"ui/*": ["./src/ui/*"],
"shared/*": ["./src/shared/*"]
}
}
}
```
Восемь алиасов — ровно по числу слоёв. Других алиасов в проекте нет.
## Правила
- **Каждый импорт между модулями — через алиас слоя.** Относительные пути (`../../`) запрещены за пределами своего модуля.
- **Внутри одного модуля** допустимы относительные импорты (`./model`, `./ui/button`) — это часть инкапсуляции модуля.
- **Префикс `@/` не используется.** Имя слоя — само по себе адрес.
- **Направление импортов** определяется архитектурой, не алиасами. Алиас разрешает импорт технически, но не отменяет правила слоёв (→ [Слои](/docs/basics/architecture/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'
```

114
projects/nextjs-style-guide/canons/applied/biome.md Normal file
View File

@@ -0,0 +1,114 @@
---
title: Biome
description: Установка и настройка линтера-форматтера в новом проекте.
keywords: [biome, линтер, форматтер, lint, format, biome.json, "@biomejs/biome", замена eslint, замена prettier]
---
# Biome
Установка и настройка линтера-форматтера в новом проекте.
## Требования
- 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` к стандартному виду (см. «Стандартный `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`, заменяется стандартным конфигом проекта.
Стандартный `biome.json`:
```jsonc
{
"$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true
},
"files": {
"ignoreUnknown": true,
"includes": ["**", "!node_modules", "!.next", "!dist", "!build", "!.templates", "!src/infra/**/generated"]
},
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentWidth": 2,
"lineWidth": 120
},
"javascript": {
"formatter": {
"quoteStyle": "single",
"jsxQuoteStyle": "double"
}
},
"linter": {
"enabled": true,
"rules": {
"recommended": true,
"suspicious": {
"noUnknownAtRules": "off"
},
"correctness": {
"noUnknownMediaFeatureName": "off"
}
},
"domains": {
"next": "recommended",
"react": "recommended"
}
},
"assist": {
"actions": {
"source": {
"organizeImports": "on"
}
}
}
}
```
`src/infra/**/generated` исключается из Biome, потому что generated-файлы не правятся руками. При этом generated-файлы остаются в git.
Правила `suspicious/noUnknownAtRules` и `correctness/noUnknownMediaFeatureName` отключены, потому что проектный CSS-стек использует `@custom-media` и другие конструкции, которые Biome может не распознавать.
## Интеграция с VS Code
Расширение `biomejs.biome` и автоформатирование при сохранении настраиваются в [VS Code](/docs/applied/vscode).

165
projects/nextjs-style-guide/canons/applied/component.md Normal file
View File

@@ -0,0 +1,165 @@
---
title: Компонент
description: Как должен выглядеть сгенерированный React-компонент внутри SLM-модуля.
---
# Компонент
Как должен выглядеть сгенерированный React-компонент внутри SLM-модуля.
## Назначение
Архитектурное определение компонента описано в разделе [Модули → Компонент](/docs/basics/architecture/modules#компонент), а структура сегмента `ui/` — в разделе [Сегменты → ui/](/docs/basics/architecture/segments#сегмент-ui).
Эта страница не повторяет архитектурные ограничения. Она показывает, каким должен быть результат генерации компонента: структура папки, `.tsx`, типы, стили и локальный экспорт.
::: danger Компоненты не создаются вручную
Компоненты в проекте создаются только через кодогенератор: через [VS Code](/docs/applied/templates/templates-usage#через-vs-code) или [CLI](/docs/applied/templates/templates-usage#через-cli).
Ручное создание компонента запрещено. Это грубое нарушение правил работы в проекте для разработчика и AI-ассистента.
Если в проекте нет шаблона `.templates/component`, сначала создайте шаблон по разделу [Создание шаблонов](/docs/applied/templates/templates-create), и только потом генерируйте компонент на его основе.
:::
## Создание
1. Проверьте, что в проекте есть шаблон `.templates/component`.
2. Если шаблона нет — создайте его по разделу [Создание шаблонов](/docs/applied/templates/templates-create).
3. Сгенерируйте компонент через [VS Code или CLI](/docs/applied/templates/templates-usage).
Структура и код ниже показывают ожидаемый результат генерации. Их нельзя использовать как инструкцию для ручного создания файлов.
## Структура
Компонент размещается в `ui/{component-name}/` родительского модуля.
Для каждого компонента обязательны `.tsx`, типы, стили и локальный `index.ts`.
```text
user-card/
└── ui/
└── user-status/
├── styles/
│ └── user-status.module.css
├── types/
│ └── user-status-props.type.ts
├── user-status.tsx
└── index.ts
```
## Реализация
Пример ниже показывает файлы базового компонента.
### Типы
Файл типов делится на три части:
- `UserStatusParams` — собственные параметры компонента. Здесь лежат только данные, которые нужны именно этому компоненту.
- `RootAttrs` — параметры корневой обёртки: `div`, `span`, `a`, `button` или другого HTML-элемента. Если компонент сам управляет `children`, они исключаются через `Omit`.
- `UserStatusProps` — итоговые пропсы компонента. Тип объединяет собственные параметры и параметры корневой обёртки.
Собственные параметры и их поля документируются по правилам раздела [Документирование → Типы, интерфейсы, enum](/docs/basics/documentation#типы-интерфейсы-enum).
`user-card/ui/user-status/types/user-status-props.type.ts`
```ts
import type { ComponentPropsWithoutRef } from 'react'
/**
* Параметры UserStatus.
*/
export type UserStatusParams = {
/** Текст статуса пользователя. */
label: string
/** Доступен ли пользователь сейчас. */
isOnline: boolean
}
/** Атрибуты корневого элемента без children. */
type RootAttrs = Omit<ComponentPropsWithoutRef<'span'>, 'children'>
export type UserStatusProps = RootAttrs & UserStatusParams
```
### TSX
В `.tsx` лежит только сам компонент:
- Компонент объявляется через `const` и именованный экспорт.
- `React.FC` не используется.
- Параметры компонента типизируются через `Props`.
- Возвращаемый тип не указывается: TypeScript корректно выводит JSX-результат, а явный `ReactElement` сужает допустимые варианты возврата.
- JSDoc-комментарий обязателен и пишется по правилам раздела [Документирование → Компоненты](/docs/basics/documentation#компоненты).
- Пропсы деструктурируются в теле компонента, а не в сигнатуре.
- Из пропсов обязательно выделяются `className` и `...rootAttrs`.
- Функция конкатенации CSS-классов импортируется и именуется `cl`.
- Корневой CSS-класс всегда называется `.root`.
Комментарий описывает назначение и сценарии применения компонента, а не DOM-разметку или внутреннюю реализацию.
`className` — внешний CSS-класс, который родитель может передать компоненту. `rootAttrs` — остальные атрибуты корневой обёртки: `id`, `aria-*`, `data-*`, обработчики событий и другие HTML-атрибуты. Они прокидываются на корневой DOM-элемент компонента.
`.root` нужен, чтобы в DevTools быстро находить корневой DOM-узел компонента и одинаково подключать внешний `className` к реальному корню.
`user-card/ui/user-status/user-status.tsx`
```tsx
import cl from 'clsx'
import type { UserStatusProps } from './types/user-status-props.type'
import styles from './styles/user-status.module.css'
/**
* Статус пользователя в карточке профиля.
*
* Используется для:
* - отображения текущей доступности пользователя
* - визуального выделения онлайн- и офлайн-состояний
*/
export const UserStatus = (props: UserStatusProps) => {
const { label, isOnline, className, ...rootAttrs } = props
return (
<span
{...rootAttrs}
className={cl(styles.root, isOnline && styles.online, className)}
>
{label}
</span>
)
}
```
### Стили
`user-card/ui/user-status/styles/user-status.module.css`
```css
.root {
display: inline-flex;
align-items: center;
gap: 6px;
color: var(--color-text-muted);
}
.root::before {
content: '';
width: 6px;
height: 6px;
border-radius: 50%;
background: currentColor;
}
.online {
color: var(--color-success);
}
```
### Локальный экспорт
`user-card/ui/user-status/index.ts`
```ts
export { UserStatus } from './user-status'
export type { UserStatusProps } from './types/user-status-props.type'
```

51
projects/nextjs-style-guide/canons/applied/creating-project/from-template.md Normal file
View File

@@ -0,0 +1,51 @@
---
title: Создание проекта из шаблона
description: Создание нового проекта на основе готового шаблона.
keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект]
---
# Создание проекта из шаблона
Создание нового проекта на основе готового шаблона.
## Что внутри
Шаблон — готовый скелет проекта с применёнными правилами стайлгайда:
- **Стек:** Next.js (App Router), TypeScript, React.
- **Архитектура:** структура папок по SLM, алиасы импортов.
- **Качество кода:** Biome (линтер и форматтер), настройки VS Code.
- **Стили:** PostCSS Modules с плагинами, токены, медиа-брейкпоинты.
- **Ассеты:** генерация SVG-спрайтов.
- **Кодогенерация:** шаблоны для страниц, компонентов, хуков, сторов.
## Установка
1. Склонировать шаблон в родительском каталоге будущего проекта:
```bash
npx tiged git@gromlab.ru:templates/nextjs.git my-app
```
`tiged` копирует снимок репозитория без истории git. Имя каталога (`my-app`) заменяется на нужное.
2. Установить зависимости:
```bash
cd my-app
npm install
```
3. Проверить сборку:
```bash
npm run build
```
Сборка должна завершиться без ошибок.
## Правила
- **Шаблон — источник истины.** Не добавлять, не удалять и не переименовывать файлы шаблона «для приведения к канону»: шаблон уже канонический. Любое несоответствие — баг шаблона, а не проекта.
- **Менеджер пакетов — npm.** Отклонение (pnpm, yarn, bun) — только по явному решению с пониманием, что стайлгайд этого не предусматривает.
- **Не инициализировать git заново** автоматически. `tiged` намеренно не создаёт `.git/` — решение о репозитории принимает разработчик.

90
projects/nextjs-style-guide/canons/applied/creating-project/manual.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: Создание проекта вручную
description: Поэтапное создание нового проекта без использования шаблона.
keywords: [создать проект, новый проект, с нуля, init, initialize, scaffold, create-next-app, начать проект, поднять проект, эталонный проект, ручная установка]
---
# Создание проекта вручную
Поэтапное создание нового проекта без использования шаблона.
## Состав эталонного проекта
| Компонент | Роль | Раздел |
|-----------|------|--------|
| Next.js | Фреймворк (роутинг, сборка, SSR) | [Next.js](/docs/applied/creating-project/nextjs) |
| Алиасы | Импорты по слоям SLM | [Алиасы](/docs/applied/aliases) |
| Biome | Линтер и форматтер (замена ESLint + Prettier) | [Biome](/docs/applied/biome) |
| Стили | Глобальные токены и breakpoints | [Стили](/docs/applied/styles/styles-setup) |
| PostCSS | CSS-процессор для custom-media и вложенности | [PostCSS](/docs/applied/postcss) |
| SVG-спрайты | Иконки через `<SvgSprite/>`, управление цветом | [SVG-спрайты](/docs/applied/svg-sprites/svg-sprites-setup) |
| VS Code | Настройки редактора и расширения | [VS Code](/docs/applied/vscode) |
| Шаблоны генерации | `.templates/` для `@gromlab/create` | [Шаблоны генерации](/docs/applied/templates/templates-setup) |
Убрать компонент из состава — значит согласованно отказаться от части стайлгайда. Частичные проекты возможны (только Next.js, Next.js + стили и т.п.), но не являются эталоном.
## Канон раскладки
В `src/` допустимы только слои SLM: `app/`, `layouts/`, `screens/`, `widgets/`, `business/`, `infra/`, `ui/`, `shared/`. Любая другая папка в `src/` — нарушение канона ([Структура проекта](/docs/applied/project-structure), [Архитектура](/docs/basics/architecture/)).
В частности: `src/app/` содержит только файлы роутинга Next.js и инициализации, без каталогов `styles/`, `assets/`, `components/`.
## Порядок установки
Подсистемы ставятся в фиксированном порядке — он отражает зависимости между шагами.
### 1. Next.js
Скелет фреймворка — обязательный первый шаг, остальное опирается на него.
См. [Next.js](/docs/applied/creating-project/nextjs). После выполнения проверки этого раздела `npm run build` должен проходить.
### 2. Алиасы
Заменить дефолтный `"@/*"` в `tsconfig.json` на канонический список из восьми слой-префиксов.
См. [Алиасы](/docs/applied/aliases).
### 3. Biome
Линтер и форматтер. Подключается **до** написания кода, иначе в проекте копятся несогласованные правки.
См. [Biome](/docs/applied/biome).
### 4. Стили (базовая инфраструктура)
Файлы `variables.css`, `media.css`, `global.css` в `src/shared/styles/` и подключение `global.css` в `src/app/layout.tsx`. CSS-процессор на этом шаге не ставится.
См. [Стили](/docs/applied/styles/styles-setup).
### 5. PostCSS
CSS-процессор поверх базовых стилей: `@custom-media`, вложенность, autoprefixer. Ставится **только после шага 4** — опирается на `src/shared/styles/media.css`.
См. [PostCSS](/docs/applied/postcss).
### 6. SVG-спрайты
Пакет `@gromlab/svg-sprites`, генерация спрайт-файла и React-компонента `<SvgSprite/>`.
См. [SVG-спрайты](/docs/applied/svg-sprites/svg-sprites-setup).
### 7. VS Code
Расширения и настройки редактора. Опирается на установленный Biome (форматирование при сохранении) и PostCSS (ассоциация `*.css`).
См. [VS Code](/docs/applied/vscode).
### 8. Шаблоны генерации
Папка `.templates/` для генератора модулей `@gromlab/create`.
См. [Шаблоны генерации](/docs/applied/templates/templates-setup).
## Правила
- **Порядок шагов фиксирован.** Перестановка ломает зависимости (PostCSS требует базовых стилей, VS Code — установленного Biome).
- **Между шагами обязательна проверка** из соответствующего раздела. Не переходить дальше, пока чеклист текущего шага не пройден.
- **Слои `src/`** (`layouts/`, `screens/`, `widgets/`, `business/`, `infra/`, `ui/`) не создавать авансом. Появляются по мере первого модуля. Исключения — `src/app/` (создаётся `create-next-app`), `src/shared/styles/` (шаг 1) и `src/shared/sprites/icons/` (шаг 6).
- **Посторонние каталоги в `src/`** (`assets/`, `utils/`, `lib/`, `components/` и т.п.) — запрещены.
- **Подмножество шагов допустимо.** Можно ставить только Next.js и часть инструментов; полный набор — это эталон, а не обязательство.

112
projects/nextjs-style-guide/canons/applied/creating-project/nextjs.md Normal file
View File

@@ -0,0 +1,112 @@
---
title: Чистая установка Next.js
description: "Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку."
keywords: [next.js, create-next-app, npx, установка, инициализация, фреймворк, скаффолдинг, app router, typescript]
---
# Чистая установка Next.js
Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
## Требования
- Node.js 18.18+ (рекомендуется LTS 20+).
- npm 10+.
- Рабочая папка пуста, либо для установки выбрана подпапка (`create-next-app@16+` отказывается ставиться в непустую директорию).
## Установка
### 1. Инициализация через `create-next-app`
Флаги зафиксированы и не согласовываются — это канон стайлгайда:
```bash
npx create-next-app@latest my-app \
--typescript \
--app \
--src-dir \
--import-alias "@/*" \
--no-eslint \
--no-tailwind \
--use-npm
```
| Флаг | Значение | Почему так |
|------|----------|------------|
| `--typescript` | TS включён | Стайлгайд требует TypeScript ([Типизация](/docs/basics/typing)) |
| `--app` | App Router | Pages Router не используется |
| `--src-dir` | Код в `src/` | Архитектура SLM требует `src/` ([Структура проекта](/docs/applied/project-structure)) |
| `--import-alias "@/*"` | Placeholder | Требуется флагом; после установки `paths` полностью переписывается на слой-префиксы (см. [Алиасы](/docs/applied/aliases)) |
| `--no-eslint` | ESLint не ставится | Линтер и форматтер — Biome ([Biome](/docs/applied/biome)) |
| `--no-tailwind` | Tailwind не ставится | Стилизация — PostCSS Modules ([Стили](/docs/applied/styles/styles-usage)) |
| `--use-npm` | Пакетный менеджер — npm | Единый инструмент в проектах |
### 2. Очистить дефолтный шаблон
`create-next-app` генерирует демо-страницу со стилями и ассетами, а Next.js 16+ дополнительно кладёт в корень собственные `AGENTS.md` и `CLAUDE.md` — всё это удаляется.
```bash
rm src/app/page.module.css
rm src/app/globals.css
rm public/next.svg public/vercel.svg public/file.svg public/globe.svg public/window.svg
rm -f AGENTS.md CLAUDE.md
```
Заменить `src/app/page.tsx` на минимальный:
```tsx
// src/app/page.tsx
export default function HomePage() {
return <h1>Home</h1>
}
```
Очистить `src/app/layout.tsx` от импорта шрифтов и `globals.css`:
```tsx
// src/app/layout.tsx
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: 'App',
description: '',
}
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ru">
<body>{children}</body>
</html>
)
}
```
### 3. Создать папку `src/shared/styles/`
Глобальные стили в SLM-архитектуре живут в слое `shared`, а не в `src/app/` ([Структура проекта](/docs/applied/project-structure)).
```bash
mkdir -p src/shared/styles
```
Остальные слои (`layouts/`, `screens/`, `widgets/`, `business/`, `infra/`, `ui/`) заводятся при появлении первого модуля в них. `src/shared/styles/` — единственный подкаталог `shared/`, который заводится сразу: без него не настроить стили на следующих шагах.
## Правила
- **Конфликт с непустой директорией** — не удалять файлы пользователя автоматически. Ставить в подпапку или временно перенести посторонние файлы.
- **Отклонение от канонических флагов** (pnpm, Tailwind, ESLint и т.п.) — только осознанное, с пониманием, что стайлгайд этого не предусматривает.
- **Слои `src/`** не создавать авансом — появляются при первом модуле. Алиасы прописываются сразу на все восемь слоёв (см. [Алиасы](/docs/applied/aliases)).
- **`AGENTS.md` от Next.js** удаляется в шаге 2. Повторно не создаётся.
- **Biome, стили, PostCSS, SVG-спрайты, VS Code** — отдельные шаги установки, не в этом разделе.
## Проверка установки
- В корне проекта: `next.config.ts`, `tsconfig.json`, `package.json`.
- В `package.json`: Next.js установлен, нет `eslint`, `tailwindcss`.
- В `src/app/` присутствуют минимальные `page.tsx` и `layout.tsx`. `globals.css`, `page.module.css` отсутствуют. Каталогов `styles/`, `assets/`, `providers/`, `components/` в `src/app/` нет.
- Папка `src/shared/styles/` создана (пустая).
- В `src/` из слоёв SLM присутствуют только `app/` и `shared/` (с `styles/`). Посторонних каталогов нет.
- В `public/` удалены `next.svg`, `vercel.svg`, `file.svg`, `globe.svg`, `window.svg`.
- В корне проекта нет `AGENTS.md` и `CLAUDE.md` от Next.js.
- `npm run build` завершается успешно.
- Пакетный менеджер — npm (нет `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`).

121
projects/nextjs-style-guide/canons/applied/data-fetch/business-composition.md Normal file
View File

@@ -0,0 +1,121 @@
---
title: Business-композиция
description: Когда REST-данные нужно объединить или интерпретировать в бизнес-модуле.
keywords: [rest, business, композиция, hooks, domain, isAuth]
---
# Business-композиция
Business-композиция используется, когда простого GET-метода или прозрачного GET-хука недостаточно: нужно объединить несколько источников, преобразовать DTO или вычислить доменное состояние.
## Когда использовать
- Нужно объединить несколько GET-запросов.
- Нужно вычислить `isAuth`, `canEdit`, `hasAccess`, `hasPets`.
- Нужно преобразовать DTO в доменную модель.
- Нужно спрятать бизнес-сценарий за доменным API.
Такая логика не пишется в `infra/`. REST-клиент остаётся прозрачным адаптером к API.
## Пример поверх одного GET-хука
```ts
// src/business/pets/hooks/use-available-pets.hook.ts
import { StatusEnum, useGetPetList } from 'infra/pet-store-api'
/**
* Доменный список доступных питомцев.
*/
export const useAvailablePets = () => {
const query = useGetPetList({ status: StatusEnum.Available })
return {
...query,
hasPets: Boolean(query.data?.length),
}
}
```
`useGetPetList` — infra-хук. `hasPets` — бизнес-интерпретация, поэтому она появляется в `business/pets`.
## Пример композиции нескольких GET-хуков
```ts
// src/business/pets/hooks/use-pets-dashboard.hook.ts
import { StatusEnum, useGetPetList } from 'infra/pet-store-api'
/**
* Данные dashboard по питомцам.
*/
export const usePetsDashboard = () => {
const availablePets = useGetPetList({ status: StatusEnum.Available })
const pendingPets = useGetPetList({ status: StatusEnum.Pending })
const soldPets = useGetPetList({ status: StatusEnum.Sold })
return {
availablePets,
pendingPets,
soldPets,
total:
(availablePets.data?.length ?? 0) +
(pendingPets.data?.length ?? 0) +
(soldPets.data?.length ?? 0),
}
}
```
Композиция нескольких запросов не добавляется в `infra/pet-store-api/hooks/`, потому что это уже сценарий потребления данных.
## Пример auth-состояния
```ts
// src/business/auth/hooks/use-auth-state.hook.ts
import { useGetCurrentUser } from 'infra/backend-api'
/**
* Состояние авторизации текущего пользователя.
*/
export const useAuthState = () => {
const currentUser = useGetCurrentUser()
const user = currentUser.data
return {
...currentUser,
user,
isAuth: Boolean(user),
}
}
```
`isAuth` не является частью REST-клиента. Это доменный смысл результата запроса.
## Где размещать
```text
src/business/
└── pets/
├── hooks/
│ └── use-available-pets.hook.ts
├── mappers/
│ └── map-pet-dto-to-pet.ts
├── types/
└── index.ts
```
Модуль `business/` экспортирует наружу готовый доменный API через `index.ts`.
## Что запрещено
```ts
// Плохо — business-смысл внутри infra-хука
export const useGetPetList = (params?: FindPetsByStatusParams | null) => {
const query = useSWR(...)
return {
...query,
hasPets: Boolean(query.data?.length),
}
}
```
REST-модуль отвечает за доступ к API. Business-модуль отвечает за смысл этих данных в продукте.

88
projects/nextjs-style-guide/canons/applied/data-fetch/client-get-hook.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: Клиентский GET-хук
description: Получение REST-данных в Client Components через готовые GET-хуки REST-клиента.
keywords: [rest, client components, swr, get-хук, client state]
---
# Клиентский GET-хук
Клиентский GET-хук используется, когда данные зависят от состояния браузера: вкладки, фильтра, поиска, пагинации, модалки или действия пользователя.
## Когда использовать
- Запрос зависит от client state.
- Данные не обязательны для первого HTML.
- Пользователь меняет параметры запроса на клиенте.
- Нужны SWR-кеширование, дедупликация и ревалидация.
## Пример с вкладками
```tsx
'use client'
import { useState } from 'react'
import { StatusEnum, useGetPetList } from 'infra/pet-store-api'
const statuses = [StatusEnum.Available, StatusEnum.Pending, StatusEnum.Sold]
export function PetTabs() {
const [status, setStatus] = useState(StatusEnum.Available)
const { data: pets, isLoading, error } = useGetPetList({ status })
return (
<section>
<div>
{statuses.map((item) => (
<button key={item} type="button" onClick={() => setStatus(item)}>
{item}
</button>
))}
</div>
{isLoading && <div>Загрузка...</div>}
{error && <div>Ошибка загрузки</div>}
<ul>
{pets?.map((pet) => (
<li key={pet.id}>{pet.name}</li>
))}
</ul>
</section>
)
}
```
Компонент выбирает параметр `status`, но не знает про SWR-ключ и fetcher. Запрос выполняет готовый GET-хук REST-клиента.
## Если хука нет
Хук добавляется в REST-модуль сервиса:
```text
src/infra/pet-store-api/hooks/use-get-pet-list.hook.ts
```
Не создавайте локальный `useSWR` в компоненте.
## Плохо
```tsx
// Плохо — прямой вызов клиента в useEffect
useEffect(() => {
petStoreApi.pet.findPetsByStatus({ status }).then(setPets)
}, [status])
// Плохо — useSWR в компоненте
const { data } = useSWR(
['pet-store-api', `/pet/findByStatus?status=${status}`],
() => petStoreApi.pet.findPetsByStatus({ status }),
)
```
Такой код теряет единое место для ключей, дублирует fetcher и разносит инфраструктурные детали по UI.
## Когда выбрать другую стратегию
- Данные нужны до первого HTML — [Серверный await](/docs/applied/data-fetch/server-await).
- Клиентский хук должен получить начальные данные сразу — [Начальные данные для клиентских хуков](/docs/applied/data-fetch/client-hooks-initial-data).
- Нужно вычислить бизнес-состояние — [Business-композиция](/docs/applied/data-fetch/business-composition).

117
projects/nextjs-style-guide/canons/applied/data-fetch/client-hooks-initial-data.md Normal file
View File

@@ -0,0 +1,117 @@
---
title: Начальные данные для клиентских хуков
description: Как дать клиентским GET-хукам начальные REST-данные.
keywords: [rest, swr, fallback, initial data, client hooks, unstable_serialize, isr, ssr]
---
# Начальные данные для клиентских хуков
Как дать клиентским GET-хукам начальные REST-данные.
Эта стратегия используется, когда данные должны быть запущены на сервере, но потребляться на клиенте через GET-хуки REST-клиента.
Технически это делается через `SWRConfig fallback`: сервер передаёт промис в fallback, а клиентский хук использует тот же SWR-ключ.
## Когда использовать
- Внутри страницы есть Client Components с GET-хуками.
- Нужно начать загрузку данных на сервере раньше.
- Клиентский компонент должен остаться обычным потребителем `useGetPetList(...)`.
- Не нужно писать отдельный prop-drilling для начальных данных.
## Рендер страницы
Перед этой стратегией сначала определите рендер маршрута. Серверный preload для `fallback` подчиняется тем же правилам, что и любой серверный запрос в `page.tsx` или `layout.tsx`.
Если данные общие и могут обновляться по интервалу, сохраняйте static/ISR. Если preload зависит от cookie, headers, `searchParams`, `no-store` или персональных данных пользователя, маршрут становится dynamic/SSR.
`SWRConfig fallback` не должен быть причиной отключать ISR на всякий случай. Он только передаёт клиентскому GET-хуку данные, которые уже были запущены на сервере.
## Ключ хука
```ts
// src/infra/pet-store-api/hooks/use-get-pet-list.hook.ts
export const getPetListKey = (params?: FindPetsByStatusParams | null) => {
if (!params?.status) {
return null
}
return ['pet-store-api', `/pet/findByStatus?status=${params.status}`] as const
}
```
Ключ экспортируется из REST-модуля, потому что он нужен и GET-хуку, и серверному `SWRConfig fallback`.
## Пример layout
```tsx
// src/app/(routes)/pets/layout.tsx
import type { ReactNode } from 'react'
import { SWRConfig, unstable_serialize } from 'swr'
import {
getPetListKey,
petStoreApi,
StatusEnum,
} from 'infra/pet-store-api'
type PetsLayoutProps = {
children: ReactNode
}
export default async function PetsLayout({ children }: PetsLayoutProps) {
const params = { status: StatusEnum.Available }
const availablePetsPromise = petStoreApi.pet.findPetsByStatus(params)
return (
<SWRConfig
value={{
fallback: {
[unstable_serialize(getPetListKey(params))]: availablePetsPromise,
},
}}
>
{children}
</SWRConfig>
)
}
```
Если GET-хук использует array-key, ключ для `fallback` сериализуется через `unstable_serialize`.
## Клиентский компонент
```tsx
'use client'
import { StatusEnum, useGetPetList } from 'infra/pet-store-api'
export function PetList() {
const { data: pets, isLoading } = useGetPetList({
status: StatusEnum.Available,
})
if (isLoading) return <div>Загрузка...</div>
return (
<ul>
{pets?.map((pet) => (
<li key={pet.id}>{pet.name}</li>
))}
</ul>
)
}
```
Компонент не знает, что данные были запущены на сервере. Он использует обычный GET-хук REST-клиента.
## Что важно
- Ключ `fallback` должен совпадать с ключом GET-хука.
- `fallback` использует ту же key-функцию и те же params, что и GET-хук.
- Серверный код вызывает метод клиента, а не GET-хук.
- Клиентский компонент вызывает GET-хук, а не `useSWR` напрямую.
- Эта стратегия не означает ручную работу с кешем в компонентах.
## Когда не использовать
Если данные нужны только серверному компоненту, используйте [Серверный await](/docs/applied/data-fetch/server-await). Если данные зависят от состояния браузера, используйте [Клиентский GET-хук](/docs/applied/data-fetch/client-get-hook).

100
projects/nextjs-style-guide/canons/applied/data-fetch/index.md Normal file
View File

@@ -0,0 +1,100 @@
---
title: Получение данных
description: Как получать данные с учётом рендера страницы.
keywords: [rest, стратегии, render, isr, ssr, server components, swr, promise, business]
---
# Получение данных
Как получать данные с учётом рендера страницы.
Перед выбором стратегии должен быть настроен REST-клиент сервиса. Если клиента ещё нет, начните с раздела [Настройка REST-клиента](/docs/applied/rest-client/setup/).
## Сначала определите рендер страницы
В Next.js выбор начинается не с `await`, `Suspense` или SWR. Сначала нужно понять, какой рендер получится у маршрута: static/ISR или dynamic/SSR.
Next.js может перевести страницу в dynamic rendering автоматически, если в маршруте используются API текущего запроса. Поэтому первый вопрос такой:
```text
Можно ли сохранить ISR, или странице нужны данные на каждый request?
```
ISR — приоритет. Если данные общие для пользователей и их можно обновлять с интервалом, не переводите страницу в SSR без необходимости.
SSR/dynamic rendering выбирается только когда данные действительно зависят от текущего request или должны пересчитываться на каждый запрос.
## Что переводит страницу в dynamic rendering
Проверьте, нужны ли странице API и настройки, которые делают маршрут динамическим:
- `cookies()` — данные зависят от cookie текущего пользователя.
- `headers()` — данные зависят от request headers.
- `draftMode()` — нужен preview/draft-режим.
- `searchParams` в `page.tsx` — данные зависят от query string.
- `cache: 'no-store'` или `revalidate: 0` в методе клиента — запрос нельзя кешировать.
- `connection()` — рендер явно ждёт request.
- `export const dynamic = 'force-dynamic'` — SSR включён вручную.
Если ничего из этого не нужно, сначала проектируйте страницу как static/ISR. Серверный `await` сам по себе не означает SSR: режим зависит от кеширования запроса и dynamic API маршрута.
## Рендер перед стратегией
| Рендер | Когда подходит | Что выбирать дальше |
|--------|----------------|---------------------|
| Static/ISR | Данные общие и могут обновляться по интервалу | Серверные стратегии: `await`, `Promise.all`, передача промиса ниже, SWR `fallback` |
| SSR/dynamic | Данные зависят от request, пользователя или должны быть свежими на каждый запрос | Серверные стратегии с учётом блокировки первого HTML |
| После гидрации | Данные зависят от вкладки, фильтра, поиска, пагинации или действия пользователя | Клиентский GET-хук |
## Как выбрать стратегию
Когда режим рендера понятен, выбирайте конкретный способ получения данных:
| Ситуация после выбора рендера | Стратегия | Где читать |
|-------------------------------|-----------|------------|
| Данные обязательны для первого HTML, SEO, `notFound()` или `redirect()` | Серверный `await` | [Серверный await](/docs/applied/data-fetch/server-await) |
| Несколько независимых данных нужны до рендера | Запуск промисов + `Promise.all` | [Параллельные серверные запросы](/docs/applied/data-fetch/parallel-server-requests) |
| Часть UI можно загрузить отдельно | Передача промиса ниже + `Suspense` | [Передача промиса ниже](/docs/applied/data-fetch/pass-promise-down) |
| Client Component должен получить данные сразу из SWR | Начальные данные для клиентских хуков | [Начальные данные для клиентских хуков](/docs/applied/data-fetch/client-hooks-initial-data) |
| Данные зависят от client state | Клиентский GET-хук | [Клиентский GET-хук](/docs/applied/data-fetch/client-get-hook) |
| Нужно объединить несколько запросов или вычислить `isAuth`, `canEdit`, `hasPets` | Business-композиция | [Business-композиция](/docs/applied/data-fetch/business-composition) |
## Правило выбора
Не выбирайте стратегию по любимому инструменту. Выбирайте её по двум вопросам:
```text
Можно ли сохранить ISR?
Где нужны данные и что должно произойти до первого HTML?
```
Если данные можно кешировать между пользователями — сохраняйте static/ISR. Если данные request-specific — используйте SSR/dynamic rendering. Если данные зависят от состояния браузера — используйте GET-хук REST-клиента. Если простой GET превращается в доменный сценарий — переходите в `business/`.
## Общие запреты
```tsx
// Плохо — SSR включён на всякий случай
export const dynamic = 'force-dynamic'
// Плохо — ISR отключён без требования к свежести на каждый request
export const revalidate = 0
// Плохо — прямой fetch в компоненте
useEffect(() => {
fetch('/api/pets').then(...)
}, [])
// Плохо — useSWR в компоненте
const { data } = useSWR(
['pet-store-api', '/pet/findByStatus?status=available'],
() => petStoreApi.pet.findPetsByStatus({ status: StatusEnum.Available }),
)
// Плохо — бизнес-флаг внутри GET-хука REST-клиента
return {
...query,
hasPets: Boolean(query.data?.length),
}
```
Не отключайте ISR без причины. В компонентах используются готовые методы клиента или готовые хуки. SWR-ключи, fetcher и транспорт остаются внутри REST-модуля.

94
projects/nextjs-style-guide/canons/applied/data-fetch/parallel-server-requests.md Normal file
View File

@@ -0,0 +1,94 @@
---
title: Параллельные серверные запросы
description: Как запускать независимые REST-запросы на сервере без waterfall.
keywords: [rest, promise.all, параллельные запросы, server components]
---
# Параллельные серверные запросы
Если серверному компоненту нужно несколько независимых данных, запускайте запросы до ожидания результата. Последовательный `await` создаёт waterfall и замедляет рендер.
## Когда использовать
- Запросы независимы друг от друга.
- Все данные нужны текущему серверному компоненту перед возвратом UI.
- Нельзя или не нужно стримить часть UI отдельно.
## Хорошо
```tsx
import { petStoreApi, StatusEnum } from 'infra/pet-store-api'
import { PetsDashboardScreen } from 'screens/pets-dashboard'
export default async function PetsDashboardPage() {
const availablePetsPromise = petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Available,
})
const pendingPetsPromise = petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Pending,
})
const soldPetsPromise = petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Sold,
})
const [availablePets, pendingPets, soldPets] = await Promise.all([
availablePetsPromise,
pendingPetsPromise,
soldPetsPromise,
])
return (
<PetsDashboardScreen
availablePets={availablePets}
pendingPets={pendingPets}
soldPets={soldPets}
/>
)
}
```
## Плохо
```tsx
export default async function PetsDashboardPage() {
const availablePets = await petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Available,
})
const pendingPets = await petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Pending,
})
const soldPets = await petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Sold,
})
return (
<PetsDashboardScreen
availablePets={availablePets}
pendingPets={pendingPets}
soldPets={soldPets}
/>
)
}
```
Во втором примере каждый следующий запрос ждёт предыдущий, хотя они независимы.
## Зависимые запросы
Если второй запрос зависит от результата первого, последовательный `await` допустим:
```tsx
export default async function OrderPage({ params }: OrderPageProps) {
const { id } = await params
const order = await petStoreApi.store.getOrderById({ orderId: Number(id) })
const pet = await petStoreApi.pet.getPetById({ petId: order.petId })
return <OrderScreen order={order} pet={pet} />
}
```
Не превращайте зависимый сценарий в `Promise.all` искусственно.
## Когда выбрать другую стратегию
Если часть данных не обязательна для первого блока UI, можно запустить промис выше и передать его ниже: [Передача промиса ниже](/docs/applied/data-fetch/pass-promise-down).

64
projects/nextjs-style-guide/canons/applied/data-fetch/pass-promise-down.md Normal file
View File

@@ -0,0 +1,64 @@
---
title: Передача промиса ниже
description: Как запускать серверный REST-запрос выше и ожидать его во вложенном server-компоненте.
keywords: [rest, promise, suspense, streaming, server components]
---
# Передача промиса ниже
Серверный компонент может запустить запрос и передать промис вложенному server-компоненту. Это полезно, когда часть UI можно загрузить отдельно через `Suspense`.
## Когда использовать
- Верхняя часть страницы может отрендериться без этих данных.
- Данные нужны только вложенному server-компоненту.
- Нужна `Suspense`-граница и серверный стриминг.
## Пример
```tsx
// src/app/(routes)/pets/page.tsx
import { Suspense } from 'react'
import { petStoreApi, StatusEnum } from 'infra/pet-store-api'
import { PetListSection } from 'widgets/pet-list-section'
import { PetListSkeleton } from 'widgets/pet-list-section'
import type { Pet } from 'infra/pet-store-api'
export default function PetsPage() {
const petsPromise = petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Available,
})
return (
<main>
<h1>Питомцы</h1>
<Suspense fallback={<PetListSkeleton />}>
<AvailablePets petsPromise={petsPromise} />
</Suspense>
</main>
)
}
async function AvailablePets({ petsPromise }: { petsPromise: Promise<Pet[]> }) {
const pets = await petsPromise
return <PetListSection pets={pets} />
}
```
Запрос стартует в `PetsPage`, но ожидание происходит внутри `AvailablePets`. `Suspense` управляет fallback для этой части UI.
## Граница стратегии
Эта стратегия остаётся серверной. Не используйте её как замену GET-хукам в Client Components.
Если данные должны попасть в клиентский SWR-хук, используйте [Начальные данные для клиентских хуков](/docs/applied/data-fetch/client-hooks-initial-data).
## Что не делать
```tsx
// Плохо — передавать промис в произвольный клиентский компонент без ясной стратегии
return <PetListClient petsPromise={petsPromise} />
```
Для клиентского потребления есть отдельная стратегия через `SWRConfig fallback` и готовые GET-хуки REST-клиента.

88
projects/nextjs-style-guide/canons/applied/data-fetch/server-await.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: Серверный await
description: Получение REST-данных на сервере до первого HTML.
keywords: [rest, server components, await, nextjs, isr, ssr, notFound, redirect]
---
# Серверный await
Получение REST-данных на сервере до первого HTML.
Серверный `await` — базовая стратегия для данных, которые нужны до рендера страницы или серверного блока.
## Когда использовать
- Данные нужны для первого HTML.
- Данные влияют на `metadata`.
- По результату запроса нужно вызвать `notFound()` или `redirect()`.
- Компонент серверный и данные не зависят от состояния браузера.
## Влияние на рендер
Серверный `await` сам по себе не означает SSR. В App Router страница может остаться static/ISR, если маршрут не использует dynamic API и запросы можно кешировать.
ISR — приоритет для общих данных. Если список или детальная страница могут обновляться по интервалу, сохраняйте кеширование и не добавляйте `no-store`, `revalidate: 0` или `force-dynamic` без требования.
SSR/dynamic rendering нужен, когда данные зависят от текущего request: cookie, headers, `searchParams`, preview-режим или персональные данные пользователя.
## Пример страницы списка
```tsx
// src/app/(routes)/pets/page.tsx
import { petStoreApi, StatusEnum } from 'infra/pet-store-api'
import { PetsScreen } from 'screens/pets'
export default async function PetsPage() {
const pets = await petStoreApi.pet.findPetsByStatus({
status: StatusEnum.Available,
})
return <PetsScreen pets={pets} />
}
```
`page.tsx` получает данные первого рендера и передаёт их ниже. UI страницы остаётся в `screens/`, а не пишется прямо в `app/`.
## Пример детальной страницы
```tsx
// src/app/(routes)/pets/[id]/page.tsx
import { notFound } from 'next/navigation'
import { petStoreApi } from 'infra/pet-store-api'
import { PetDetailScreen } from 'screens/pet-detail'
type PetPageProps = {
params: Promise<{ id: string }>
}
export default async function PetPage({ params }: PetPageProps) {
const { id } = await params
const pet = await petStoreApi.pet.getPetById({ petId: Number(id) }).catch(() => null)
if (!pet) {
notFound()
}
return <PetDetailScreen pet={pet} />
}
```
Обработка 404 зависит от API-клиента и класса ошибок. В примере показана идея: решение о `notFound()` принимается на уровне маршрута, а не внутри REST-клиента.
## Что не делать
```tsx
// Плохо — хуки нельзя вызывать в Server Component
const { data } = useGetPetList({ status: StatusEnum.Available })
// Плохо — прямой fetch в обход клиента
const response = await fetch('https://petstore3.swagger.io/api/v3/pet/findByStatus')
```
Если данные нужны на сервере, вызывайте метод REST-клиента напрямую.
## Когда выбрать другую стратегию
- Несколько независимых запросов — [Параллельные серверные запросы](/docs/applied/data-fetch/parallel-server-requests).
- Часть UI можно грузить отдельно — [Передача промиса ниже](/docs/applied/data-fetch/pass-promise-down).
- Данные нужны клиентскому хуку сразу после гидрации — [Начальные данные для клиентских хуков](/docs/applied/data-fetch/client-hooks-initial-data).

128
projects/nextjs-style-guide/canons/applied/fonts.md Normal file
View File

@@ -0,0 +1,128 @@
---
title: Шрифты
description: Как подключать шрифты через Next.js Font в проекте.
---
# Шрифты
Как подключать шрифты через Next.js Font в проекте.
## Назначение
Шрифты подключаются через `next/font`. Это стандартный способ Next.js: шрифты загружаются без ручных `<link>`, `@font-face` и настройки preconnect.
Шрифт подключается в точке инициализации приложения, а в CSS используется через переменную.
## Google Fonts
```tsx
// src/app/layout.tsx
import type { ReactNode } from 'react'
import { Inter } from 'next/font/google'
import 'shared/styles/global.css'
const inter = Inter({
subsets: ['latin', 'cyrillic'],
variable: '--font-main',
display: 'swap',
})
type RootLayoutProps = {
children: ReactNode
}
export default function RootLayout({ children }: RootLayoutProps) {
return (
<html lang="ru" className={inter.variable}>
<body>{children}</body>
</html>
)
}
```
```css
/* src/shared/styles/global.css */
body {
font-family: var(--font-main), system-ui, sans-serif;
}
```
## Локальные шрифты
Каждый локальный шрифт размещается в отдельной папке внутри `src/shared/fonts/`. В этой же папке лежит `.font.ts`, где объявляется `localFont`.
```text
src/shared/fonts/
└── roboto/
├── roboto.font.ts
├── Roboto-Regular.woff2
├── Roboto-Italic.woff2
├── Roboto-Bold.woff2
└── Roboto-BoldItalic.woff2
```
```ts
// src/shared/fonts/roboto/roboto.font.ts
import localFont from 'next/font/local'
export const roboto = localFont({
src: [
{
path: './Roboto-Regular.woff2',
weight: '400',
style: 'normal',
},
{
path: './Roboto-Italic.woff2',
weight: '400',
style: 'italic',
},
{
path: './Roboto-Bold.woff2',
weight: '700',
style: 'normal',
},
{
path: './Roboto-BoldItalic.woff2',
weight: '700',
style: 'italic',
},
],
variable: '--font-main',
display: 'swap',
})
```
`app/` импортирует готовый объект шрифта и только подключает его к документу:
```tsx
// src/app/layout.tsx
import type { ReactNode } from 'react'
import { roboto } from 'shared/fonts/roboto/roboto.font'
import 'shared/styles/global.css'
type RootLayoutProps = {
children: ReactNode
}
export default function RootLayout({ children }: RootLayoutProps) {
return (
<html lang="ru" className={roboto.variable}>
<body>{children}</body>
</html>
)
}
```
Путь в `localFont` указывается относительно `.font.ts`, поэтому файлы шрифта импортируются коротко: `./Roboto-Regular.woff2`.
Если шрифтов несколько, у каждого своя папка и свой `.font.ts`.
## Правила
- Использовать `next/font/google` или `next/font/local`.
- Не подключать шрифты через ручные `<link>` и `@font-face` без необходимости.
- Подключать шрифты один раз — в корневом layout через готовый объект шрифта.
- Использовать CSS-переменные `variable`, а не жёстко прописывать семейство в каждом компоненте.
- Локальные файлы шрифтов хранить в `src/shared/fonts/{font-name}/` рядом с `{font-name}.font.ts`.
- Не объявлять `localFont` внутри `src/app/layout.tsx`; layout только импортирует готовый шрифт.

95
projects/nextjs-style-guide/canons/applied/images.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: Изображения
description: Как подключать изображения через Next.js Image в проекте.
---
# Изображения
Как подключать изображения через Next.js Image в проекте.
## Назначение
Изображения рендерятся через компонент `Image` из `next/image`. Это сохраняет единый API для размеров, `alt`, lazy-loading и `priority`, даже если оптимизация изображений отключена.
В проекте оптимизация Next.js Image отключается через `unoptimized`, чтобы сборка и рантайм не зависели от встроенного image optimizer.
## Настройка
Отключение оптимизации задаётся глобально в `next.config.ts`:
```ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
images: {
unoptimized: true,
},
}
export default nextConfig
```
После этого `unoptimized` не нужно повторять на каждом `Image`.
## Использование
Статические изображения, доступные по URL, размещаются в `public/`:
```text
public/
└── images/
└── user-avatar.png
```
```tsx
import Image from 'next/image'
export const UserAvatar = () => {
return (
<Image
src="/images/user-avatar.png"
alt="Аватар пользователя"
width={96}
height={96}
/>
)
}
```
## Правила
- Использовать `Image` из `next/image`, не обычный `<img>`.
- Для контентных изображений всегда писать осмысленный `alt`.
- Для декоративных изображений использовать `alt=""`.
- Указывать `width` и `height`, если изображение не использует `fill`.
- При `fill` задавать `sizes` и контролировать размеры родителя стилями.
- `priority` ставить только для изображений первого экрана.
- SVG-иконки не оформлять как изображения — для них используется раздел [SVG-спрайты](/docs/applied/svg-sprites/svg-sprites-intro).
## Пример с `fill`
```tsx
import Image from 'next/image'
import styles from '../styles/article-card-cover.module.css'
export const ArticleCardCover = () => {
return (
<div className={styles.root}>
<Image
src="/images/article-cover.jpg"
alt="Обложка статьи"
fill
sizes="(min-width: 768px) 33vw, 100vw"
/>
</div>
)
}
```
```css
.root {
position: relative;
aspect-ratio: 16 / 9;
overflow: hidden;
}
```

81
projects/nextjs-style-guide/canons/applied/localization.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: Локализация
description: Как организовать локализацию как infra-модуль.
---
# Локализация
Как организовать локализацию как infra-модуль.
## Назначение
Локализация — инфраструктурная подсистема приложения. Она отвечает за текущую локаль, словари, форматирование переводов и API для компонентов.
Код локализации живёт в `src/infra/i18n/`. Компоненты и модули не читают словари напрямую — они используют публичный API infra-модуля.
## Структура
```text
src/infra/i18n/
├── config/
│ └── i18n.config.ts
├── dictionaries/
│ ├── ru.ts
│ └── en.ts
├── hooks/
│ └── use-translation.hook.ts
├── providers/
│ └── i18n-provider.tsx
├── types/
│ └── i18n.type.ts
└── index.ts
```
Набор сегментов может отличаться, но публичная точка входа остаётся одна — `infra/i18n`.
## Подключение
`app/` только подключает готовый провайдер локализации. Реализация провайдера, словари и конфиг остаются в `infra/i18n/`.
```tsx
// src/app/layout.tsx
import type { ReactNode } from 'react'
import { I18nProvider } from 'infra/i18n'
type RootLayoutProps = {
children: ReactNode
}
export default function RootLayout({ children }: RootLayoutProps) {
return (
<html lang="ru">
<body>
<I18nProvider locale="ru">{children}</I18nProvider>
</body>
</html>
)
}
```
## Использование
Компоненты получают переводы через готовый API модуля локализации:
```tsx
import { useTranslation } from 'infra/i18n'
export const ProfileTitle = () => {
const { t } = useTranslation()
return <h1>{t('profile.title')}</h1>
}
```
## Правила
- Локализация живёт в `infra/i18n/`.
- `app/` только подключает готовый provider и передаёт locale.
- Словари не импортируются напрямую в компоненты, screens или business-модули.
- Ключи переводов не собираются динамически из строк, если это ломает типизацию и поиск.
- Тексты интерфейса не хардкодятся в переиспользуемых компонентах, если они должны переводиться.
- Форматирование дат, чисел и валют должно проходить через API локализации или отдельные утилиты infra-модуля.

156
projects/nextjs-style-guide/canons/applied/module.md Normal file
View File

@@ -0,0 +1,156 @@
---
title: Модуль
description: Как должен выглядеть сгенерированный SLM-модуль в проекте.
---
# Модуль
Как должен выглядеть сгенерированный SLM-модуль в проекте.
## Назначение
Архитектурное определение модуля описано в разделе [Архитектура → Модули](/docs/basics/architecture/modules). Список сегментов описан в разделе [Архитектура → Сегменты](/docs/basics/architecture/segments).
Эта страница показывает прикладное оформление трёх типов модулей: UI, бизнес и инфраструктурный.
## Создание
1. Проверьте, что в проекте есть нужный шаблон в `.templates/`.
2. Если шаблона нет — создайте его по разделу [Создание шаблонов](/docs/applied/templates/templates-create).
3. Сгенерируйте модуль через [VS Code или CLI](/docs/applied/templates/templates-usage).
## Типы модулей
Архитектура определяет три типа модулей ([Типы модулей](/docs/basics/architecture/modules#типы-модулей)):
| Тип | Обязательный файл | Описание |
|---|---|---|
| UI-модуль | `{name}.tsx` | Модуль, выросший из компонента |
| Бизнес-модуль | `{name}.factory.ts` | Модуль вокруг публичного runtime API |
| Инфраструктурный модуль | нет | Модуль вокруг технического сервиса |
## UI-модуль
UI-модуль — это компонент, который перерос ограничения компонента: получил собственные хуки, вложенные модули в `parts/`, сценарную логику или публичный API. Внутренняя структура та же, что у компонента: корневой `.tsx`, типы, стили, `ui/`. Но без ограничений компонента.
Подробное оформление компонентов внутри `ui/` описано в разделе [Компонент](/docs/applied/component).
## Бизнес-модуль
Бизнес-модуль строится вокруг публичного runtime API. Ключевой файл — фабрика (`{name}.factory.ts`), которая возвращает всё, что нужно внешнему коду в runtime.
Архитектурное описание фабрики: [Архитектура → Фабрика](/docs/basics/architecture/modules#фабрика).
### Структура
```text
business/customer/
├── customer.factory.ts
├── index.ts
└── types/
├── customer.type.ts
├── customer-api.type.ts
├── customer-deps.type.ts
└── customer-factory.type.ts
```
### Типы
`business/customer/types/customer-api.type.ts`
```ts
export type CustomerApi = {
useCustomer: () => Customer
CustomerCard: (props: CustomerCardProps) => ReactNode
}
```
`business/order/types/order-deps.type.ts`
```ts
export type OrderDeps = {
customer: Pick<CustomerApi, 'useCustomer'>
}
```
`business/order/types/order-factory.type.ts`
```ts
export type OrderFactory = (deps: OrderDeps) => OrderApi
```
### Фабрика без зависимостей
`business/customer/customer.factory.ts`
```ts
import type { CustomerFactory } from './types/customer-factory.type'
export const customerFactory: CustomerFactory = () => {
return {
useCustomer,
CustomerCard,
}
}
```
### Фабрика с зависимостями
`business/order/order.factory.ts`
```ts
import type { OrderFactory } from './types/order-factory.type'
export const orderFactory: OrderFactory = (deps) => {
return {
useOrder,
OrderCard,
}
}
```
### Композиция на уровне screen
```tsx
// screens/home/home.screen.tsx
import { customerFactory } from '@/business/customer'
import { orderFactory } from '@/business/order'
const customer = customerFactory()
const order = orderFactory({ customer })
const { useOrder, OrderCard } = order
export const HomeScreen = () => {
const currentOrder = useOrder()
return <OrderCard order={currentOrder} />
}
```
## Инфраструктурный модуль
Инфраструктурный модуль строится вокруг технического сервиса или интеграции. Его структура определяется природой сервиса — фиксированного корневого файла нет.
Архитектурное описание: [Архитектура → Типы модулей → Инфраструктурный модуль](/docs/basics/architecture/modules#инфраструктурный-модуль).
Пример модуля темы:
```text
theme/
├── index.ts
├── config/
├── hooks/
├── styles/
└── ui/
```
Пример модуля API-клиента:
```text
backend-api/
├── backend-api.client.ts
├── config/
├── types/
└── index.ts
```

186
projects/nextjs-style-guide/canons/applied/page-level.md Normal file
View File

@@ -0,0 +1,186 @@
---
title: Файлы роутинга
description: Как работать со страницами и другими файлами роутинга Next.js App Router.
---
# Файлы роутинга
Как работать со страницами и другими файлами роутинга Next.js App Router.
## Назначение
`src/app/**` — точка входа приложения и слой файлового роутинга Next.js.
Файлы роутинга не реализуют интерфейс. Они описывают маршрут: читают параметры, получают данные первого рендера, подготавливают кеш или состояние и передают результат в screen.
Границы слоя описаны в [Архитектура → Слои → App](/docs/basics/architecture/layers#слой-app).
## Граница ответственности
| Область | Где живёт |
|---|---|
| Файлы маршрутов (`page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`) | `src/app/**` |
| Параметры маршрута, `metadata`, `redirect()`, `notFound()` | `src/app/**` |
| Серверные запросы для первого рендера | `src/app/**`, через готовые клиенты и сервисы нижних слоёв |
| Прогрев SWR-кеша, начальное состояние, подключение провайдеров | `src/app/**`, только через готовые обёртки из нижних слоёв |
| UI страницы | `screens/` |
| Каркас страницы: header, footer, sidebar | `layouts/` |
| Провайдеры, сторы, хуки, API-клиенты, сервисы | нижние слои (`screens/`, `business/`, `infra/`, `shared/`) |
| CSS Modules и стили компонентов | рядом с компонентами, не в `src/app/**` |
## Что можно делать в `page.tsx`
- Экспортировать `metadata` или `generateMetadata`.
- Читать `params` и `searchParams`.
- Нормализовать и валидировать параметры маршрута.
- Делать серверные запросы для первого рендера через готовые клиенты или сервисы.
- Вызывать `redirect()` и `notFound()`.
- Готовить начальные данные для screen.
- Готовить SWR `fallback` и передавать его в готовый провайдер.
- Подключать готовый провайдер стора страницы и передавать начальное состояние.
- Рендерить screen или композицию из готовых обёрток и screen.
## Что запрещено
- Писать UI-разметку страницы прямо в файле роутинга.
- Создавать локальные компоненты внутри `src/app/**`.
- Добавлять CSS Modules, стили компонентов, `components/`, `styles/`, `hooks/`, `stores/`, `services/` внутри `src/app/**`.
- Реализовывать провайдеры, сторы, хуки, API-клиенты или сервисы в файлах роутинга.
- Размещать бизнес-логику, мапперы и правила предметной области в файлах роутинга.
- Вызывать `useSWR` и доменные клиентские хуки в файлах роутинга.
## Страницы
Страница объявляется через `export default function`. Для серверных запросов используется `async function`.
```tsx
import type { Metadata } from 'next'
import { ProfileScreen } from 'screens/profile'
export const metadata: Metadata = {
title: 'Профиль',
description: 'Страница профиля пользователя',
}
type ProfilePageProps = {
params: Promise<{ id: string }>
}
export default async function ProfilePage({ params }: ProfilePageProps) {
const { id } = await params
return <ProfileScreen id={id} />
}
```
## Данные первого рендера
Если данные нужны до первого рендера, `page.tsx` получает их на сервере и передаёт в screen. Сам запрос выполняется через готовый клиент или сервис нижнего слоя.
```tsx
import { notFound } from 'next/navigation'
import { userApi } from 'infra/backend-api'
import { UserScreen } from 'screens/user'
type UserPageProps = {
params: Promise<{ id: string }>
}
export default async function UserPage({ params }: UserPageProps) {
const { id } = await params
const user = await userApi.users.get(id)
if (!user) {
notFound()
}
return <UserScreen user={user} />
}
```
Если данные нужны нескольким клиентским SWR-хукам, файл роутинга может обернуть дерево в `SWRConfig` и передать `fallback`. Запросы стартуют на сервере, а клиентские хуки получают данные из кеша.
Ключи `fallback` должны совпадать с ключами внутри GET-хуков REST-клиента. Для array-key используется `unstable_serialize`.
```tsx
import type { ReactNode } from 'react'
import { SWRConfig, unstable_serialize } from 'swr'
import {
backendApi,
getCurrentUserKey,
getPostListKey,
} from 'infra/backend-api'
type FeedLayoutProps = {
children: ReactNode
}
export default async function FeedLayout({ children }: FeedLayoutProps) {
const userPromise = backendApi.user.getCurrent()
const postsPromise = backendApi.posts.list()
return (
<SWRConfig
value={{
fallback: {
[unstable_serialize(getCurrentUserKey())]: userPromise,
[unstable_serialize(getPostListKey())]: postsPromise,
},
}}
>
{children}
</SWRConfig>
)
}
```
Подробнее о стратегиях запросов и начальных данных для клиентских хуков: [Получение данных](/docs/applied/data-fetch/), [Начальные данные для клиентских хуков](/docs/applied/data-fetch/client-hooks-initial-data).
## Инициализация состояния
Файл роутинга может подключить готовый провайдер стора страницы, если состояние зависит от маршрута или данных первого рендера. Реализация стора и провайдера не размещается в `src/app/**`.
```tsx
import { ProfileScreen, ProfileStoreProvider } from 'screens/profile'
type ProfilePageProps = {
params: Promise<{ id: string }>
}
export default async function ProfilePage({ params }: ProfilePageProps) {
const { id } = await params
return (
<ProfileStoreProvider initialState={{ userId: id }}>
<ProfileScreen />
</ProfileStoreProvider>
)
}
```
## Layout
`layout.tsx` подключает готовую инициализацию приложения: глобальные стили, провайдеры и верхнеуровневые обёртки из нижних слоёв.
Вёрстка layout-каркаса выносится в слой `layouts/`. Реализация провайдеров, стилей и UI не размещается в `app/`.
## Error и Not Found
`error.tsx` и `not-found.tsx` делегируют разметку готовым screen или widget. В файле роутинга остаётся только адаптация API Next.js к пропсам нижнего слоя.
```tsx
'use client'
import { ErrorScreen } from 'screens/error'
type ErrorPageProps = {
error: Error & { digest?: string }
reset: () => void
}
const ErrorPage = ({ error, reset }: ErrorPageProps) => {
return <ErrorScreen error={error} reset={reset} />
}
export default ErrorPage
```

70
projects/nextjs-style-guide/canons/applied/postcss.md Normal file
View File

@@ -0,0 +1,70 @@
---
title: PostCSS
description: Установка и настройка CSS-процессора в новом проекте.
keywords: [postcss, postcss.config.mjs, postcss-custom-media, postcss-nesting, autoprefixer, postcss-global-data, csstools, "@custom-media", "@nest", css-процессор]
---
# PostCSS
Установка и настройка CSS-процессора в новом проекте.
## Зачем 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/styles-usage), раздел «Импорт стилей»).

101
projects/nextjs-style-guide/canons/applied/project-structure.md Normal file
View File

@@ -0,0 +1,101 @@
---
title: Структура проекта
description: Из чего состоит проект и где что лежит.
---
# Структура проекта
Из чего состоит проект и где что лежит.
## Корень репозитория
```text
project-root/
├── .templates/ # Шаблоны для генерации модулей
├── .vscode/ # Настройки и рекомендуемые расширения VS Code
├── public/ # Статика, доступная по прямому URL
├── src/ # Исходный код приложения
├── .env.example # Переменные окружения проекта (шаблон)
├── .env # Переменные окружения проекта (не коммитить)
├── .gitignore
├── AGENTS.md # Инструкции для AI-агентов
├── biome.json # Линтер и форматтер (вместо ESLint + Prettier)
├── next.config.ts # Конфигурация Next.js
├── package.json # Зависимости и скрипты
├── postcss.config.mjs # Конфигурация PostCSS
└── tsconfig.json # Конфигурация TypeScript
```
## Папка `public/`
Хранит статические файлы, которые отдаются по прямому URL без обработки сборщиком:
```text
public/
└── og-image.png
```
Компоненты, стили и другой исходный код здесь не размещаются.
## Папка `src/`
```text
src/
├── app/ # Роутинг Next.js и точка входа приложения
├── layouts/ # Каркасы страниц (header, footer, sidebar)
├── screens/ # Контент конкретной страницы
├── widgets/ # Составные блоки интерфейса, не привязанные к домену
├── business/ # Бизнес-домены (auth, catalog, orders)
├── infra/ # Техсервисы (theme, i18n, API-адаптеры)
├── ui/ # UI-кит без бизнес-логики
└── shared/ # Общие ресурсы (утилиты, типы, стили)
```
Принципы организации слоёв описаны в разделе [Архитектура](../basics/architecture/).
### Папка `app/`
Точка входа приложения и файловый роутинг Next.js (`layout.tsx`, `page.tsx`, route-сегменты).
`app/` подключает готовую инициализацию из нижних слоёв, но не реализует провайдеры, стили, UI-компоненты, хуки, сторы или сервисы.
Подробнее о границах слоя: [Архитектура → Слои → App](/docs/basics/architecture/layers#слой-app).
```text
src/app/
├── layout.tsx # Корневой layout
└── page.tsx # Главная страница
```
## Папка `.templates/`
Содержит шаблоны для генерации кода. Каждый подкаталог — шаблон отдельного типа модуля:
```text
.templates/
├── component/ # Шаблон компонента
├── screen/ # Шаблон экрана
├── layout/ # Шаблон layout
├── widget/ # Шаблон виджета
├── module/ # Шаблон бизнес-модуля
└── store/ # Шаблон стора
```
Подробнее о генерации описано в разделе [Шаблоны генерации](/docs/applied/templates/templates-intro).
## Конфигурационные файлы
| Файл | Назначение |
|---|---|
| `next.config.ts` | Настройки Next.js: редиректы, переменные окружения, webpack |
| `tsconfig.json` | Настройки TypeScript: пути, строгость, таргет |
| `biome.json` | Правила линтера и форматтера Biome |
| `postcss.config.mjs` | Подключение PostCSS-плагинов (CSS Modules, custom media) |
| `package.json` | Зависимости, версии, npm-скрипты |
| `AGENTS.md` | Инструкции для AI-агентов, работающих в проекте |
## Переменные окружения
- `.env` — переменные окружения проекта, запрещено коммитить
- `.env.example` — шаблон, коммитится в репозиторий
Переменные с префиксом `NEXT_PUBLIC_` доступны в клиентском коде. Остальные доступны только на сервере.

50
projects/nextjs-style-guide/canons/applied/rest-client/index.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: REST-клиент
description: Настройка REST-клиента сервиса для работы с внешним API.
keywords: [rest, api, данные, infra, клиент, swr, стратегии]
---
# REST-клиент
Настройка REST-клиента сервиса для работы с внешним API.
## Настройка
Для каждого внешнего сервиса создаётся отдельный API-клиент: `pet-store-api`, `billing-api`, `maps-api`.
На этом этапе внешний API оформляется как модуль слоя `infra/`.
Клиент отвечает за:
- генерацию или ручное описание методов API;
- настройку `baseUrl`;
- заголовки и авторизацию;
- обработку ошибок;
- кастомизацию и расширение типов;
- GET-хуки для клиентских компонентов;
- прямое использование методов клиента в серверном коде и submit-функциях;
- публичный API модуля.
Если у API есть OpenAPI-спецификация — клиент генерируется автоматически. Если OpenAPI нет или он неполный — клиент создаётся вручную.
GET-хуки относятся к клиенту, потому что это прозрачные SWR-обёртки над GET-методами этого клиента.
Подробнее:
- [Настройка REST-клиента](/docs/applied/rest-client/setup/)
- [Автогенерация из OpenAPI](/docs/applied/rest-client/setup/auto)
- [Ручное создание](/docs/applied/rest-client/setup/manual)
- [GET-хуки REST-клиента](/docs/applied/rest-client/setup/hooks)
- [Использование REST-клиента](/docs/applied/rest-client/usage)
## Как читать раздел
Если API ещё не подключён — начните с [Настройки REST-клиента](/docs/applied/rest-client/setup/).
Если клиент уже создан и нужно вызвать его методы — откройте [Использование REST-клиента](/docs/applied/rest-client/usage).
Если клиент уже есть, но непонятно как получить данные — начните с раздела [Получение данных](/docs/applied/data-fetch/).
Если данные нужны в Client Component — сначала проверьте, есть ли [GET-хук REST-клиента](/docs/applied/rest-client/setup/hooks).
Если в коде появляется бизнес-смысл вроде `isAuth`, `canEdit`, `hasAccess` — это уже не REST-клиент, а `business/`.

272
projects/nextjs-style-guide/canons/applied/rest-client/setup/auto.md Normal file
View File

@@ -0,0 +1,272 @@
---
title: Автогенерация REST-клиента
description: Генерация REST-клиента из OpenAPI-спецификации.
keywords: [rest, openapi, api-codegen, автогенерация, generated, npx]
---
# Автогенерация REST-клиента
Генерация REST-клиента из OpenAPI-спецификации.
## Когда использовать
Автогенерация используется, когда у API есть актуальная OpenAPI-спецификация. Генератор создаёт TypeScript-клиент, типы и методы API, а разработчик вручную добавляет настройку клиента и GET-хуки.
## Пример API
В примерах используется Swagger Petstore:
```text
https://petstore3.swagger.io/api/v3/openapi.json
```
Имена модуля:
```text
src/infra/pet-store-api/
petStoreApi
pet-store-api.generated.ts
```
## Скрипт генерации
`@gromlab/api-codegen` не устанавливается в `devDependencies`. Используем `npx @gromlab/api-codegen@latest`, чтобы запускать свежую версию.
```json
{
"scripts": {
"codegen:pet-store-api": "npx @gromlab/api-codegen@latest -i https://petstore3.swagger.io/api/v3/openapi.json -o src/infra/pet-store-api/generated -n pet-store-api.generated"
}
}
```
Параметры:
- `-i` — путь к OpenAPI-спецификации: URL или локальный файл.
- `-o` — директория для сгенерированного файла.
- `-n` — имя сгенерированного файла без `.ts`.
Ключ `--swr` не используется. GET-хуки REST-клиента пишутся вручную, чтобы сохранить проектный контракт: один GET-хук = один GET-метод, без бизнес-логики и композиции.
## Генерация
```bash
npm run codegen:pet-store-api
```
Ожидаемый результат:
```text
src/infra/pet-store-api/generated/
└── pet-store-api.generated.ts
```
Сгенерированный файл не правится руками и коммитится в репозиторий.
## Проверка методов
После генерации откройте `generated/pet-store-api.generated.ts` и проверьте фактические имена методов.
Для Petstore нужны GET-операции вида:
```ts
petStoreApi.pet.findPetsByStatus({ status: StatusEnum.Available })
petStoreApi.pet.getPetById({ petId: 10 })
```
Точные сигнатуры зависят от OpenAPI-схемы и версии генератора. В рабочих задачах всегда сверяйтесь с generated-файлом.
## Алгоритм для агента
После генерации агент должен действовать по шагам:
1. Открыть `generated/{service-name}.generated.ts`.
2. Найти фактические имена GET-методов клиента.
3. Для каждого нужного GET-метода найти generated-тип параметров и тип ответа.
4. Создать или обновить `client.ts` только для настройки транспорта и экспорта инстанса клиента.
5. Создать GET-хуки только для реально нужных GET-методов, не для всех методов API на всякий случай.
6. Для каждого GET-хука создать key-функцию формата `[serviceName, endpoint]`.
7. В key-функции вернуть `null`, если обязательные параметры не готовы.
8. В хуке принять `params?: GeneratedParams | null` и `config?: SWRConfiguration<Data>`.
9. В fetcher вызвать generated-метод клиента с `params as GeneratedParams`.
10. Экспортировать хук и key-функцию из `hooks/index.ts`.
11. Экспортировать наружу только нужные generated-типы, generated enum, DTO и `hooks` через корневой `index.ts`.
Что агент не должен делать:
- Не использовать ключ `--swr` генератора.
- Не править `generated/*.generated.ts` руками.
- Не добавлять GET-хуки для POST, PUT, PATCH, DELETE.
- Не добавлять бизнес-флаги, тосты, редиректы и UI-состояние в GET-хук.
- Не создавать словари enum-маппинга внутри GET-хука.
- Не объявлять DTO и response-типы в файле хука.
- Не вызывать `useSWR` условно.
- Не добавлять `throw` в fetcher для неготовых params.
## `client.ts`
Сгенерированный код не должен напрямую использоваться из приложения. Сначала создаётся настроенный инстанс клиента.
```ts
// src/infra/pet-store-api/client.ts
import { Api, HttpClient } from './generated/pet-store-api.generated'
const baseUrl = process.env.NEXT_PUBLIC_PET_STORE_API_BASE_URL
if (!baseUrl) {
throw new Error('NEXT_PUBLIC_PET_STORE_API_BASE_URL is required')
}
const httpClient = new HttpClient({
baseUrl,
baseApiParams: {
secure: false,
headers: {
'Content-Type': 'application/json',
},
},
})
export const petStoreApi = new Api(httpClient)
```
Локальное значение `NEXT_PUBLIC_PET_STORE_API_BASE_URL` задаётся в `.env.local`. Не добавляйте fallback вроде `?? 'http://localhost:8080/api/v3'` или `?? ''`: если env-переменная не задана, клиент должен падать с явной ошибкой конфигурации.
`client.ts` не содержит расширения типов, `declare module` и `Extended`-типы. Он только настраивает транспорт и экспортирует инстанс клиента.
## GET-хуки
GET-хуки пишутся вручную после проверки generated-методов.
Пример для generated-метода `petStoreApi.pet.getPetById({ petId })`:
```ts
// src/infra/pet-store-api/hooks/use-get-pet-detail.hook.ts
import type { SWRConfiguration } from 'swr'
import useSWR from 'swr'
import { petStoreApi } from '../client'
import type { GetPetByIdParams, Pet } from '../generated/pet-store-api.generated'
export const getPetDetailKey = (params?: GetPetByIdParams | null) => {
if (!params?.petId) {
return null
}
return ['pet-store-api', `/pet/${params.petId}`] as const
}
/**
* Получает детальную карточку питомца с кешированием результата.
*/
export const useGetPetDetail = (
params?: GetPetByIdParams | null,
config?: SWRConfiguration<Pet>,
) => {
const key = getPetDetailKey(params)
const fetcher = () => petStoreApi.pet.getPetById(params as GetPetByIdParams)
return useSWR<Pet>(key, fetcher, config)
}
```
Подробный контракт key-функций, `params`, `config` и запретов описан в разделе [GET-хуки REST-клиента](/docs/applied/rest-client/setup/hooks).
## Расширение сгенерированных типов
Сгенерированный файл не правится руками. Если OpenAPI-спецификация неполная или генератор дал слишком общий тип (`object`, `unknown`, отсутствующее поле), расширения живут в `types/`.
```text
src/infra/biocad-less-api/
├── generated/
│ └── biocad-less-api.generated.ts
├── types/
│ ├── term.ts
│ └── index.ts
├── client.ts
└── index.ts
```
Пример расширения generated-типа:
```ts
// src/infra/biocad-less-api/types/term.ts
import type { TermRecordItem } from '../generated/biocad-less-api.generated'
declare module '../generated/biocad-less-api.generated' {
interface TermRecordItem {
media?: {
file?: string
title?: string
url?: string
}
}
}
export type TermRecordItemExtended = Omit<
TermRecordItem,
'categories' | 'tags' | 'fields'
> & {
categories?: Array<{
_id?: string
id?: string
slug?: string
name?: string
}>
tags?: Array<{
_id?: string
id?: string
slug?: string
name?: string
}>
fields?: Record<string, unknown>
}
```
```ts
// src/infra/biocad-less-api/types/index.ts
export type { TermRecordItemExtended } from './term'
```
`declare module` используется для добавления отсутствующих полей в generated-интерфейс. `Extended`-тип используется, когда нужно переопределить неточные поля, не трогая generated-файл.
## Публичный API
```ts
// src/infra/pet-store-api/index.ts
export { petStoreApi } from './client'
export type {
FindPetsByStatusParams,
GetPetByIdParams,
Pet,
} from './generated/pet-store-api.generated'
export { PetStatusEnum, StatusEnum } from './generated/pet-store-api.generated'
export * from './hooks'
```
Наружу импортируют только из `infra/pet-store-api`, не из `generated/`.
Если у модуля есть расширенные типы, они тоже реэкспортируются через `index.ts`:
```ts
// src/infra/biocad-less-api/index.ts
export type { TermRecordItemExtended } from './types'
```
## Регенерация
При изменении OpenAPI-схемы:
```bash
npm run codegen:pet-store-api
```
Что меняется:
- `generated/pet-store-api.generated.ts` — перезаписывается генератором.
- `client.ts`, `hooks/`, `types/`, `index.ts` — не трогаются автоматически.
Если после регенерации поменялись сигнатуры методов или типы, это исправляется в ручном коде модуля.
## Следующий шаг
После генерации и настройки `client.ts` проверьте [использование REST-клиента](/docs/applied/rest-client/usage) или добавьте [GET-хук REST-клиента](/docs/applied/rest-client/setup/hooks) для Client Components.

313
projects/nextjs-style-guide/canons/applied/rest-client/setup/hooks.md Normal file
View File

@@ -0,0 +1,313 @@
---
title: GET-хуки REST-клиента
description: Прозрачные SWR-обёртки над GET-методами REST-клиента.
keywords: [rest, swr, get-хуки, client components, infra]
---
# GET-хуки REST-клиента
Прозрачные SWR-обёртки над GET-методами REST-клиента.
## Зачем нужны
GET-хуки нужны, чтобы Client Components получали REST-данные через SWR, но не работали с `useSWR`, ключами кеша и fetcher напрямую.
## Где лежат
GET-хуки принадлежат REST-клиенту конкретного сервиса и живут рядом с ним:
```text
src/infra/
└── pet-store-api/
├── client.ts
├── generated/
├── hooks/
│ ├── use-get-pet-list.hook.ts
│ ├── use-get-pet-detail.hook.ts
│ └── index.ts
├── types/
└── index.ts
```
## Контракт
- Один GET-хук = один GET-метод клиента.
- Имя GET-хука начинается с `useGet`: `useGetPetList`, `useGetPetDetail`.
- Имя файла начинается с `use-get`: `use-get-pet-list.hook.ts`.
- Хук принимает `params?: GeneratedParams | null` и `config?: SWRConfiguration<Data>`.
- Для GET-метода без параметров хук принимает только `config?: SWRConfiguration<Data>`.
- Key-функция принимает те же `params`, что и хук.
- Key-функция возвращает `null`, если обязательные параметры не готовы.
- Проверка готовности запроса живёт в key-функции, а не в теле хука.
- Хук вызывает `useSWR` один раз и безусловно.
- Fetcher не проверяет `null`, не бросает ошибку и не вызывает метод клиента с `null`.
- Внутри только SWR-механика: key, fetcher, `useSWR`, `config`.
- Хук возвращает тип ответа API: generated-тип или DTO из `types/`.
- Хук не объединяет несколько запросов.
- Хук не маппит DTO в доменную модель.
- Хук не вычисляет бизнес-флаги: `isAuth`, `canEdit`, `hasAccess`, `hasPets`.
- Хук не вызывает тосты, модалки, редиректы и не пишет UI-состояние.
## Формат SWR-ключа
SWR-ключ GET-хука всегда создаётся отдельной экспортируемой функцией.
Формат ключа:
```ts
['pet-store-api', '/pet/10'] as const
```
- Первый элемент — имя API-сервиса или REST-клиента в `kebab-case`.
- Второй элемент — endpoint запроса: path и query string.
- Key-функция возвращает `null`, когда запрос нельзя выполнять.
- Key-функция нужна и GET-хуку, и `SWRConfig fallback`.
- Не используйте произвольные части вроде `['pet-store-api', 'pet', 'detail', params]`.
- Не используйте только строку endpoint без имени сервиса.
Примеры ключей:
```ts
export const getPetDetailKey = (params?: GetPetByIdParams | null) => {
if (!params?.petId) {
return null
}
return ['pet-store-api', `/pet/${params.petId}`] as const
}
```
```ts
export const getPetListKey = (params?: FindPetsByStatusParams | null) => {
if (!params?.status) {
return null
}
return ['pet-store-api', `/pet/findByStatus?status=${params.status}`] as const
}
```
```ts
export const getPetListByTagsKey = (params?: FindPetsByTagsParams | null) => {
if (!params?.tags.length) {
return null
}
return ['pet-store-api', `/pet/findByTags?tags=${params.tags.join(',')}`] as const
}
```
Если API допускает `0` как валидный идентификатор, не используйте проверку `!params?.id`. В таком случае проверяйте `null` и `undefined` явно.
## Пример списка
```ts
// src/infra/pet-store-api/hooks/use-get-pet-list.hook.ts
import type { SWRConfiguration } from 'swr'
import useSWR from 'swr'
import { petStoreApi } from '../client'
import type {
FindPetsByStatusParams,
Pet,
} from '../generated/pet-store-api.generated'
export const getPetListKey = (params?: FindPetsByStatusParams | null) => {
if (!params?.status) {
return null
}
return ['pet-store-api', `/pet/findByStatus?status=${params.status}`] as const
}
/**
* Получает список питомцев по статусу.
*/
export const useGetPetList = (
params?: FindPetsByStatusParams | null,
config?: SWRConfiguration<Pet[]>,
) => {
const key = getPetListKey(params)
const fetcher = () => petStoreApi.pet.findPetsByStatus(
params as FindPetsByStatusParams,
)
return useSWR<Pet[]>(key, fetcher, config)
}
```
`params as FindPetsByStatusParams` допустим только в fetcher: готовность параметров проверена в key-функции, а при `key = null` SWR не вызывает fetcher.
## Пример detail-запроса
```ts
// src/infra/pet-store-api/hooks/use-get-pet-detail.hook.ts
import type { SWRConfiguration } from 'swr'
import useSWR from 'swr'
import { petStoreApi } from '../client'
import type { GetPetByIdParams, Pet } from '../generated/pet-store-api.generated'
export const getPetDetailKey = (params?: GetPetByIdParams | null) => {
if (!params?.petId) {
return null
}
return ['pet-store-api', `/pet/${params.petId}`] as const
}
/**
* Получает детальную карточку питомца с кешированием результата.
*/
export const useGetPetDetail = (
params?: GetPetByIdParams | null,
config?: SWRConfiguration<Pet>,
) => {
const key = getPetDetailKey(params)
const fetcher = () => petStoreApi.pet.getPetById(params as GetPetByIdParams)
return useSWR<Pet>(key, fetcher, config)
}
```
## Пример без параметров
```ts
// src/infra/pet-store-api/hooks/use-get-store-inventory.hook.ts
import type { SWRConfiguration } from 'swr'
import useSWR from 'swr'
import { petStoreApi } from '../client'
import type { StoreInventory } from '../types'
export const getStoreInventoryKey = () => {
return ['pet-store-api', '/store/inventory'] as const
}
/**
* Получает инвентарь магазина.
*/
export const useGetStoreInventory = (
config?: SWRConfiguration<StoreInventory>,
) => {
return useSWR<StoreInventory>(
getStoreInventoryKey(),
() => petStoreApi.store.getInventory(),
config,
)
}
```
Если generated-метод возвращает безымянный тип вроде `Record<string, number>`, а тип нужен наружу, вынесите его в `types/`.
## Отложенный запрос
GET-хук может принимать `null` или `undefined` для обязательных параметров. Это означает, что параметры ещё не готовы и запрос выполнять нельзя.
```ts
const key = getPetDetailKey(params)
```
Если `params` не готов, key-функция вернёт `null`. SWR не вызовет fetcher для `null`-ключа.
Не добавляйте отдельные `isReady`, `throw new Error(...)` и условный вызов `useSWR`.
## Экспорт
```ts
// src/infra/pet-store-api/hooks/index.ts
export { getPetListKey, useGetPetList } from './use-get-pet-list.hook'
export { getPetDetailKey, useGetPetDetail } from './use-get-pet-detail.hook'
export {
getStoreInventoryKey,
useGetStoreInventory,
} from './use-get-store-inventory.hook'
```
```ts
// src/infra/pet-store-api/index.ts
export { petStoreApi } from './client'
export type {
FindPetsByStatusParams,
GetPetByIdParams,
Pet,
} from './generated/pet-store-api.generated'
export { PetStatusEnum, StatusEnum } from './generated/pet-store-api.generated'
export * from './hooks'
export type { StoreInventory } from './types'
```
Наружу импортируют только из `infra/pet-store-api`, не из `generated/` и не из `hooks/` напрямую.
## Где заканчивается infra
```ts
// Хорошо: infra, прозрачный GET-хук
const { data: pets } = useGetPetList({ status: StatusEnum.Available })
```
```ts
// Хорошо: business, доменная интерпретация
export const useAvailablePets = () => {
const query = useGetPetList({ status: StatusEnum.Available })
return {
...query,
hasPets: Boolean(query.data?.length),
}
}
```
`hasPets` — не часть GET-запроса, поэтому он не добавляется в `useGetPetList`.
## Что запрещено
```ts
// Плохо — useSWR в компоненте
const { data } = useSWR(
['pet-store-api', '/pet/findByStatus?status=available'],
() => petStoreApi.pet.findPetsByStatus({ status: StatusEnum.Available }),
)
// Плохо — проверка готовности размазана по хуку
export const useGetPetDetail = (params?: GetPetByIdParams | null) => {
const key = params?.petId ? getPetDetailKey(params) : null
const fetcher = () => {
if (!params?.petId) {
throw new Error('Pet id is required')
}
return petStoreApi.pet.getPetById(params)
}
return useSWR<Pet>(key, fetcher)
}
// Плохо — условный вызов useSWR нарушает rules of hooks
export const useGetPetDetail = (params?: GetPetByIdParams | null) => {
const key = getPetDetailKey(params)
if (key === null) {
return useSWR(null, null)
}
return useSWR(key, () => petStoreApi.pet.getPetById(params))
}
// Плохо — несколько GET внутри infra-хука
export const usePetDashboard = () => {
const available = useGetPetList({ status: StatusEnum.Available })
const sold = useGetPetList({ status: StatusEnum.Sold })
return { available, sold }
}
// Плохо — бизнес-флаг внутри GET-хука REST-клиента
export const useGetPetList = (params?: FindPetsByStatusParams | null) => {
const query = useSWR(...)
return {
...query,
hasPets: Boolean(query.data?.length),
}
}
```
Подробное потребление таких хуков описано в стратегии [Клиентский GET-хук](/docs/applied/data-fetch/client-get-hook).

88
projects/nextjs-style-guide/canons/applied/rest-client/setup/index.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: Настройка REST-клиента
description: Подготовка REST-клиента сервиса к использованию.
keywords: [rest, клиент, infra, методы, openapi, get-хуки, swr]
---
# Настройка REST-клиента
Подготовка REST-клиента сервиса к использованию.
## Что настраиваем
REST-клиент — это infra-модуль, через который проект работает с внешним REST API.
На этапе настройки нужно подготовить клиент сервиса: оболочку клиента, методы API и GET-хуки для клиентских компонентов.
## Из чего состоит клиент
REST-клиент состоит из трёх основных частей:
1. **Клиент** — самописная оболочка над транспортом.
2. **Методы** — сгенерированные из OpenAPI или написанные вручную вызовы API.
3. **GET-хуки** — SWR-обёртки для GET-запросов.
Эти части живут в одном REST-модуле, потому что относятся к одному внешнему сервису.
## Клиент
Клиент — ручной слой, который настраивает работу с API: `baseUrl`, заголовки, авторизацию, обработку ошибок и создание инстанса сервиса.
Даже если методы генерируются из OpenAPI, `client.ts` остаётся ручным файлом проекта.
`client.ts` — только сборочная точка клиента. В нём не размещаются DTO, `declare module`, `Extended`-типы, GET-хуки и бизнес-логика.
`baseUrl` API задаётся обязательной env-переменной без fallback-значения в коде. Не используйте записи вроде `process.env.NEXT_PUBLIC_PET_STORE_API_BASE_URL ?? 'http://localhost:8080/api/v3'` или `?? ''`: локальный URL должен лежать в `.env.local`, а отсутствие переменной должно приводить к явной ошибке конфигурации.
## Методы
Методы описывают конкретные запросы к API.
Они появляются одним из двух способов:
- генерируются из OpenAPI в `generated/`;
- создаются вручную в `methods/`.
Подробности:
- [Автогенерация из OpenAPI](/docs/applied/rest-client/setup/auto)
- [Ручное создание](/docs/applied/rest-client/setup/manual)
## GET-хуки
Для GET-запросов добавляются GET-хуки REST-клиента.
Это прозрачные SWR-обёртки над GET-методами клиента. Они живут в `hooks/` этого же REST-модуля и нужны для использования данных в Client Components.
GET-хуки именуются с префиксом `useGet`: `useGetPetList`, `useGetPetDetail`, `useGetCurrentUser`.
Каждый GET-хук имеет экспортируемую key-функцию. SWR-ключ всегда имеет формат `[serviceName, endpoint]`: например `['pet-store-api', '/pet/10']`.
Хук принимает generated-параметры метода и SWR-настройки: `params?: GetPetByIdParams | null`, `config?: SWRConfiguration<Pet>`.
Подробности:
- [GET-хуки REST-клиента](/docs/applied/rest-client/setup/hooks)
## Структура модуля
```text
src/infra/{service-name}/
├── client.ts # самописная оболочка и инстанс клиента
├── generated/ или methods/ # методы API
├── hooks/ # GET-хуки REST-клиента
├── types/ # DTO, именованные response-типы и расширения типов
├── errors/ # ошибки API, если нужны
└── index.ts # публичный API
```
`index.ts` — единственная точка входа в REST-модуль для внешнего кода.
Если generated-метод возвращает безымянный тип вроде `Record<string, number>`, а этот тип нужен снаружи, вынесите его в `types/`. Не объявляйте DTO внутри `hooks/use-get-*.hook.ts`.
## Что делаем дальше
1. Создайте методы клиента: [Автогенерация из OpenAPI](/docs/applied/rest-client/setup/auto) или [Ручное создание](/docs/applied/rest-client/setup/manual).
2. Добавьте GET-хуки для GET-запросов: [GET-хуки REST-клиента](/docs/applied/rest-client/setup/hooks).
3. Проверьте прямые вызовы клиента: [Использование REST-клиента](/docs/applied/rest-client/usage).
4. После настройки клиента переходите к [Получению данных](/docs/applied/data-fetch/).

198
projects/nextjs-style-guide/canons/applied/rest-client/setup/manual.md Normal file
View File

@@ -0,0 +1,198 @@
---
title: Ручное создание REST-клиента
description: Создание REST-клиента вручную, когда OpenAPI нет или он неполный.
keywords: [rest, ручной клиент, fetch, methods, dto, errors, infra]
---
# Ручное создание REST-клиента
Создание REST-клиента вручную, когда OpenAPI нет или он неполный.
## Когда использовать
Ручной REST-клиент используется, когда у API нет OpenAPI-спецификации или она недостаточно точная для автогенерации.
Задача ручного клиента — дать такую же точку входа, как у автогенерированного клиента: именованный API-объект, методы по сущностям, DTO и GET-хуки рядом с клиентом.
## Что нужно создать
```text
src/infra/
└── pet-project-api/
├── methods/
│ └── posts.ts
├── hooks/
│ └── index.ts
├── types/
│ ├── client.ts
│ ├── post.ts
│ └── index.ts
├── errors/
│ └── pet-project-api.error.ts
├── client.ts
└── index.ts
```
| Файл | Роль |
|------|------|
| `client.ts` | Базовый транспорт и создание инстанса клиента |
| `methods/` | Методы API по сущностям |
| `types/` | DTO запросов, ответов и типы клиента |
| `errors/` | Ошибки конкретного API |
| `hooks/` | GET-хуки REST-клиента, если данные нужны в Client Components |
| `index.ts` | Публичный API REST-модуля |
## DTO и типы API
DTO запросов и ответов живут в `types/`. `client.ts` не содержит DTO и доменные типы.
```ts
// src/infra/pet-project-api/types/post.ts
export type PostDto = {
id: string
slug: string
title: string
}
export type PostListQueryDto = {
limit?: number
category?: string
}
```
```ts
// src/infra/pet-project-api/types/index.ts
export type { PostDto, PostListQueryDto } from './post'
```
Типы, которые нужны только базовому транспорту, можно держать отдельно:
```ts
// src/infra/pet-project-api/types/client.ts
export type QueryParams = Record<string, string | number | boolean>
```
## Ошибка API
Ошибка API тоже относится к REST-модулю.
```ts
// src/infra/pet-project-api/errors/pet-project-api.error.ts
export class PetProjectApiError extends Error {
constructor(
public readonly status: number,
message: string,
) {
super(message)
this.name = 'PetProjectApiError'
}
}
```
## Базовый клиент
`client.ts` содержит только транспортную оболочку и сборку инстанса. Прямой `fetch` живёт здесь, а не в компонентах и не в методах верхних слоёв.
```ts
// src/infra/pet-project-api/client.ts
import { PetProjectApiError } from './errors/pet-project-api.error'
import type { QueryParams } from './types/client'
export class PetProjectApiClient {
constructor(
private readonly baseUrl: string,
private readonly defaultHeaders: Record<string, string> = {},
) {}
async get<T>(path: string, params: QueryParams = {}): Promise<T> {
const base = `${this.baseUrl.replace(/\/+$/, '')}/`
const url = new URL(path.replace(/^\/+/, ''), base)
Object.entries(params).forEach(([key, value]) => {
url.searchParams.set(key, String(value))
})
const response = await fetch(url, {
headers: {
Accept: 'application/json',
...this.defaultHeaders,
},
})
if (!response.ok) {
throw new PetProjectApiError(response.status, response.statusText)
}
return response.json() as Promise<T>
}
}
```
Это минимальный шаблон. Авторизация, дополнительные заголовки, `next.revalidate`, `post`, `formdata` и другие детали добавляются только когда они реально нужны API.
## Методы API
Методы группируются по сущностям в `methods/`. Они не знают про React, SWR и UI.
```ts
// src/infra/pet-project-api/methods/posts.ts
import type { PetProjectApiClient } from '../client'
import type { PostDto, PostListQueryDto } from '../types/post'
export function postsMethods(client: PetProjectApiClient) {
return {
/** GET /posts */
list: (query: PostListQueryDto = {}) =>
client.get<PostDto[]>('posts', query),
/** GET /posts/{slug} */
get: (slug: string) =>
client.get<PostDto>(`posts/${slug}`),
}
}
```
Метод возвращает DTO в форме API. Если данным нужен доменный смысл, маппинг делается выше, в `business/`.
## Публичный API
`index.ts` собирает именованный API-объект и открывает наружу только публичные части модуля.
```ts
// src/infra/pet-project-api/index.ts
import { PetProjectApiClient } from './client'
import { postsMethods } from './methods/posts'
const baseUrl = process.env.NEXT_PUBLIC_PET_PROJECT_API_BASE_URL
if (!baseUrl) {
throw new Error('NEXT_PUBLIC_PET_PROJECT_API_BASE_URL is required')
}
const client = new PetProjectApiClient(
baseUrl,
{ 'Content-Type': 'application/json' },
)
export const petProjectApi = {
posts: postsMethods(client),
}
export { PetProjectApiError } from './errors/pet-project-api.error'
export type { PostDto, PostListQueryDto } from './types'
export * from './hooks'
```
Внешний код импортирует только из `infra/pet-project-api`, не из внутренних файлов модуля.
## Правила
- `fetch` используется только внутри базового клиента.
- DTO запросов и ответов живут в `types/`.
- `client.ts` не содержит DTO, GET-хуки и бизнес-логику.
- `baseUrl` берётся из обязательной env-переменной без fallback-значения в коде.
- Методы лежат в `methods/` и возвращают DTO.
- GET-хуки добавляются отдельно в `hooks/`, если данные нужны в Client Components.
- Доменные типы и маппинг DTO живут не в REST-клиенте, а в `business/`.
Следующий шаг: [Использование REST-клиента](/docs/applied/rest-client/usage), [GET-хуки REST-клиента](/docs/applied/rest-client/setup/hooks) или [Получение данных](/docs/applied/data-fetch/).

21
projects/nextjs-style-guide/canons/applied/rest-client/usage.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: Использование REST-клиента
description: Как вызвать готовый REST-клиент в функции.
keywords: [rest, api client, submit, generated, pet-store-api]
---
# Использование REST-клиента
Как вызвать готовый REST-клиент в функции.
## Пример
```ts
import { petStoreApi } from 'infra/pet-store-api'
export const getPet = async (petId: number) => {
const pet = await petStoreApi.pet.getPetById({ petId })
console.log(pet)
}
```

0
projects/nextjs-style-guide/canons/applied/stores.md Normal file
View File

176
projects/nextjs-style-guide/canons/applied/styles/styles-setup.md Normal file
View File

@@ -0,0 +1,176 @@
---
title: Настройка стилей
description: "Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили."
keywords: [variables.css, media.css, global.css, shared/styles, токены, переменные, custom-media, breakpoints, подключение стилей, базовые стили, инициализация]
---
# Настройка стилей
Подготовка стилевой основы проекта: токены, медиа-запросы, глобальные стили.
## Требования
- Установлен PostCSS или любой другой pre/post-процессор с поддержкой `@custom-media`.
## Файлы
Состав глобальных стилей — три файла:
| Файл | Роль |
|------|------|
| `variables.css` | Токены проекта (цвета, отступы, радиусы) |
| `media.css` | Custom media queries (брейкпоинты по ширине и высоте) |
| `global.css` | Точка сборки глобальных стилей: через `@import` тянет все остальные глобалы, импортируется в приложение один раз |
Правила подключения:
- В приложение импортируется **только** `global.css`.
- `variables.css` и будущие глобальные файлы (резеты, темы, типографика) подключаются в `global.css` через `@import`.
- `media.css` **не импортируется** — ни в `global.css`, ни в компоненты, ни в точку инициализации. Его читает CSS-процессор на этапе сборки (см. [PostCSS](/docs/applied/postcss)).
## Корневой `font-size`
Базовая единица `rem` в проекте привязана к **16px**: корневой `font-size` не переопределяется. `html { font-size: ... }` писать запрещено — пользовательская настройка размера шрифта в браузере должна работать (a11y). Все `rem`-значения в `media.css` и других стилях трактуются как `1rem = 16px по умолчанию`.
Reset браузерных дефолтов (`box-sizing`, сброс `margin`, типографика) каноном не задаётся — каждый проект решает сам. Если заводится — подключается через `global.css`.
## Установка
### 1. Создать файлы
```bash
mkdir -p src/shared/styles
touch src/shared/styles/variables.css src/shared/styles/media.css src/shared/styles/global.css
```
### 2. Заполнить `media.css`
Файл `src/shared/styles/media.css`. Стандартный набор брейкпоинтов проекта; редактировать только при согласованном изменении шкалы.
Единица — `rem` (реагирует на корневой `font-size`). Перевод исходит из дефолтного `html { font-size: 16px }`, т.е. `1rem = 16px`.
```css
/* src/shared/styles/media.css */
/* Ширина — Mobile First (min-width), кроме --xs (max-width) */
@custom-media --xs (max-width: 35.9375rem); /* 575px — до sm */
@custom-media --sm (min-width: 36rem); /* 576px — телефон альбом / малый планшет */
@custom-media --md (min-width: 48rem); /* 768px — планшет */
@custom-media --lg (min-width: 62rem); /* 992px — малый десктоп */
@custom-media --xl (min-width: 75rem); /* 1200px — десктоп */
@custom-media --2xl (min-width: 88rem); /* 1408px — широкий десктоп */
@custom-media --3xl (min-width: 120rem); /* 1920px — full HD+ */
/* Высота — min-height */
@custom-media --h-xs (min-height: 41.6875rem); /* 667px — iPhone SE портрет */
@custom-media --h-sm (min-height: 43.875rem); /* 702px */
@custom-media --h-md (min-height: 50.625rem); /* 810px — iPad портрет */
@custom-media --h-lg (min-height: 56.25rem); /* 900px */
@custom-media --h-xl (min-height: 62.5rem); /* 1000px */
@custom-media --h-2xl (min-height: 68.75rem); /* 1100px */
@custom-media --h-3xl (min-height: 75rem); /* 1200px */
```
Правила:
- только `@custom-media` на верхнем уровне;
- имена короткие, по шкале (`--xs` … `--3xl`); высотные — с префиксом `--h-`;
- единица — `rem`, не `em`/`px`; пиксельное значение указывается комментарием;
- значения ширины — `min-width` (Mobile First), исключение `--xs` — `max-width` (блок «строго меньше `--sm`»);
- значения высоты — `min-height`.
### 3. Заполнить `variables.css`
Файл `src/shared/styles/variables.css`. Набор токенов под проект расширяется по мере роста дизайн-системы.
```css
/* src/shared/styles/variables.css */
:root {
/* Цвета */
--color-primary: #3b82f6;
--color-bg: #ffffff;
--color-bg-hover: #f5f5f5;
--color-text: #1a1a1a;
/* Отступы */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
/* Скругления */
--radius-1: 4px;
--radius-2: 8px;
}
```
Правила:
- все токены определяются в `:root` — без вложенных селекторов;
- именование — `kebab-case` по ролям: `--color-*`, `--space-*`, `--radius-*`;
- `px` — основная единица для пространственных токенов;
- темы накладываются поверх через `[data-theme="..."] { ... }` — в отдельном файле темы или здесь же.
`variables.css` напрямую в приложение не импортируется — только через `global.css`.
### 4. Заполнить `global.css`
Файл `src/shared/styles/global.css`. Единственный глобальный файл, импортируемый в точку инициализации приложения. Внутри — `@import` остальных глобалов относительным путём.
```css
/* src/shared/styles/global.css */
@import './variables.css';
/* Сюда же подключаются будущие глобалы через @import:
* @import './reset.css';
* @import './typography.css';
* @import './themes.css';
* media.css НЕ импортируется — он работает через PostCSS.
*/
```
Правила:
- пути в `@import` — относительные (`./variables.css`), не через алиасы; нативный CSS `@import` не понимает tsconfig-paths;
- `media.css` в `global.css` **не импортируется**;
- собственные глобальные правила (`html { ... }`, `body { ... }`) писать **не здесь**, а в отдельных файлах рядом (`reset.css`, `typography.css`) и подключать через `@import`. `global.css` — только точка сборки;
- порядок `@import` определяет порядок каскада: токены первыми, дальше резеты / темы / типографика.
### 5. Подключить `global.css` в layout
Импорт делается **один раз** — в корневом layout приложения:
```tsx
// src/app/layout.tsx
import 'shared/styles/global.css'
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: 'App',
description: '',
}
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ru">
<body>{children}</body>
</html>
)
}
```
`variables.css` и `media.css` в layout **не импортируются напрямую** — только через `global.css` (variables) или через PostCSS на сборке (media).
## Проверка установки
- В `src/shared/styles/` присутствуют три файла: `variables.css`, `media.css`, `global.css`. В `src/app/` папки `styles/` нет.
- В `src/app/layout.tsx` есть `import 'shared/styles/global.css'`. Импортов `variables.css` и `media.css` там нет.
- В проекте **не появились** PostCSS-пакеты и `postcss.config.*` — этот раздел их не ставит.
- `npm run build` завершается успешно.
## Дальше
- [PostCSS](/docs/applied/postcss) — подключить процессор, чтобы заработали `@media (--md)` и вложенность.
- [Использование стилей](/docs/applied/styles/styles-usage) — правила написания CSS в компонентах.
- [SVG-спрайты](/docs/applied/svg-sprites/svg-sprites-setup) — стили иконок отдельно от глобальных.

271
projects/nextjs-style-guide/canons/applied/styles/styles-usage.md Normal file
View File

@@ -0,0 +1,271 @@
---
title: Использование стилей
description: Как пишутся стили в проекте.
---
# Использование стилей
Как пишутся стили в проекте.
## Общие правила
- Только **PostCSS** и **CSS Modules** для кастомной стилизации.
- Подход **Mobile First** — стили пишутся от мобильных к десктопу.
- Именование классов — `camelCase` (`.root`, `.buttonNext`, `.itemTitle`).
- Корневой класс каждого CSS Module компонента всегда называется `.root` — это упрощает ориентацию в DevTools и отладку DOM.
- Модификаторы — отдельный класс с `_`, применяется через `&._modifier`.
**Хорошо**
```css
.submitButton {
padding: 8px 16px;
&._disabled {
opacity: 0.5;
}
}
```
**Плохо**
```css
/* Плохо: kebab-case и вложенный элемент вместо отдельного класса. */
.submit-button {
padding: 8px 16px;
&__icon {
margin-right: 8px;
}
}
```
## Вложенность
- Вложенность селекторов запрещена.
- Исключения:
- Псевдоклассы: `&:hover`, `&:active`, `&:focus`, `&:disabled` и т.д.
- Псевдоэлементы: `&::before`, `&::after`.
- Медиа-запросы: `@media`.
- Модификаторы: `&._active`, `&._disabled`.
- Каждый вложенный блок отделяется пустой строкой от предыдущих свойств.
**Хорошо**
```css
.card {
padding: 16px;
background-color: var(--color-bg);
&:hover {
background-color: var(--color-bg-hover);
}
&::after {
content: '';
display: block;
}
&._highlighted {
border-color: var(--color-primary);
}
@media (--md) {
padding: 24px;
}
}
.cardTitle {
font-size: 16px;
@media (--md) {
font-size: 20px;
}
}
```
**Плохо**
```css
/* Плохо: вложенность селекторов, нет пустых строк между блоками. */
.card {
padding: 16px;
.cardTitle {
font-size: 16px;
}
&:hover {
background-color: var(--color-bg-hover);
}
}
```
## Медиа-запросы
- Только **Custom Media Queries**: `@media (--md) {}`.
- Запрещены произвольные breakpoints: `@media (min-width: 768px)`.
- `@media` пишется только **внутри** селектора.
- Запрещено писать `@media` на верхнем уровне с селекторами внутри.
**Хорошо**
```css
.sidebar {
display: none;
@media (--md) {
display: block;
}
}
.sidebarTitle {
font-size: 14px;
@media (--md) {
font-size: 18px;
}
}
```
**Плохо**
```css
/* Плохо: @media на верхнем уровне с селекторами внутри. */
@media (--md) {
.sidebar {
display: block;
}
.sidebarTitle {
font-size: 18px;
}
}
/* Плохо: произвольный breakpoint вместо custom media. */
.sidebar {
@media (min-width: 992px) {
display: block;
}
}
```
## CSS-переменные
- Цвета (`--color-*`), отступы (`--space-*`), скругления (`--radius-*`) определяются в `src/shared/styles/variables.css` через `:root`.
- Файл переменных подключается через `src/shared/styles/global.css`, который импортируется один раз в `src/app/layout.tsx`.
- Не дублировать магические значения в компонентах.
**Хорошо**
```css
/* src/shared/styles/variables.css */
:root {
--color-primary: #3b82f6;
--color-bg: #ffffff;
--color-bg-hover: #f5f5f5;
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--radius-1: 4px;
--radius-2: 8px;
}
```
```css
/* компонент */
.card {
padding: var(--space-3);
border-radius: var(--radius-2);
background-color: var(--color-bg);
}
```
**Плохо**
```css
/* Плохо: магические значения вместо переменных. */
.card {
padding: 12px;
border-radius: 8px;
background-color: #ffffff;
}
```
## Custom Media
- Breakpoints определяются через Custom Media Queries в `src/shared/styles/media.css`.
- Custom media подключаются глобально через конфиг PostCSS (плагин `postcss-custom-media`) — не импортировать в файлы стилей.
```css
/* src/shared/styles/media.css */
@custom-media --sm (min-width: 36em);
@custom-media --md (min-width: 62em);
@custom-media --lg (min-width: 82em);
```
## Импорт стилей
- Стили компонента импортируются только внутри своего компонента.
- Запрещено импортировать стили одного компонента в другой.
- Custom media не импортируются в файлы стилей — они подключаются глобально через конфиг PostCSS.
## Форматирование
- Пустая строка между селекторами верхнего уровня.
- Пустая строка перед каждым вложенным блоком (медиа, псевдокласс, модификатор).
**Хорошо**
```css
.userBar {
display: none;
color: var(--color-text);
@media (--md) {
display: flex;
}
}
.userBarButton {
background-color: var(--color-bg);
&:hover {
background-color: var(--color-bg-hover);
}
&._active {
background-color: var(--color-primary);
}
}
```
**Плохо**
```css
/* Плохо: нет пустых строк между селекторами и вложенными блоками. */
.userBar {
display: none;
color: var(--color-text);
@media (--md) {
display: flex;
}
}
.userBarButton {
background-color: var(--color-bg);
&:hover {
background-color: var(--color-bg-hover);
}
&._active {
background-color: var(--color-primary);
}
}
```
## Единицы измерения
- `px` — основная единица измерения.
- Остальные (`em`, `rem`, `%`, `vh`/`vw`) — допускаются по необходимости дизайна.
## Порядок CSS-свойств
В стилях рекомендуется придерживаться логического порядка свойств:
1. Позиционирование (`position`, `top`, `left`, `z-index`).
2. Блочная модель (`display`, `width`, `height`, `margin`, `padding`).
3. Оформление (`background`, `border`, `box-shadow`, `border-radius`).
4. Текст (`font`, `color`, `text-align`, `line-height`).
5. Прочее (`transition`, `animation`, `opacity`, `cursor`).
## Комментарии
- Желательно не писать комментарии в CSS.
- Исключение — нетривиальные хаки и обходные решения, к которым стоит оставить пояснение.

31
projects/nextjs-style-guide/canons/applied/svg-sprites/svg-sprites-intro.md Normal file
View File

@@ -0,0 +1,31 @@
---
title: SVG-спрайты
description: "Что такое SVG-спрайты и какие проблемы они решают."
---
# SVG-спрайты
Что такое SVG-спрайты и какие проблемы они решают.
## Проблема
Иконки в проекте — это десятки и сотни SVG-файлов, которые нужно как-то доставлять в интерфейс. Подход «один `<img>` на иконку» или инлайн SVG в каждом компоненте приводят к трём проблемам:
- **Дублирование.** Инлайн SVG в нескольких компонентах — один и тот же код размазан по проекту. Изменение иконки требует правок в десяти местах.
- **Размер бандла.** Каждый инлайн SVG — полный XML-код, который попадает в JS-бандл. Сотня иконок × средний размер SVG = сотни килобайт, которые браузер парсит как JavaScript, а не как статику.
- **Нет управления цветом.** Инлайн SVG жёстко закрашивает иконку. Сменить цвет по состоянию (`:hover`, `._disabled`) — значит дублировать SVG или городить `currentColor`-хаки в каждом компоненте.
## Решение
SVG-спрайты — это единый файл-контейнер, в который собираются все иконки проекта. В коде используется один React-компонент `<SvgSprite icon="name"/>`, а браузер загружает спрайт как статику — один раз, с кешированием.
Что дают SVG-спрайты:
- **Один источник.** Каждая иконка — один SVG-файл в `src/shared/sprites/`. Обновил файл — иконка обновилась везде.
- **Лёгкий бандл.** Спрайт отдаётся как статический файл из `public/`, не попадает в JavaScript. Типы имён иконок генерируются автоматически — автодополнение работает без ручных описаний.
- **Цвет через CSS.** При сборке цвета в SVG заменяются на CSS-переменные. Цвет иконки меняется через `color` родителя или через переменные `--icon-color-N` — как любой другой стиль.
## Состав раздела
- [Настройка](/docs/applied/svg-sprites/svg-sprites-setup) — подключение пакета, конфигурация, первая генерация.
- [Использование](/docs/applied/svg-sprites/svg-sprites-usage) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.

132
projects/nextjs-style-guide/canons/applied/svg-sprites/svg-sprites-setup.md Normal file
View File

@@ -0,0 +1,132 @@
---
title: Настройка SVG-спрайтов
description: Подключение SVG-спрайтов в новом проекте.
keywords: [svg-sprites, установка, настройка, config, пакет, "@gromlab/svg-sprites", svg-sprites.config.ts]
---
# Настройка SVG-спрайтов
Подключение SVG-спрайтов в новом проекте.
## Установка
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
```
7. Подключить спрайт в layout. Глобальный спрайт (иконки) подключается через `<link rel="preload">` в корневом layout — браузер загрузит файл заранее и закеширует:
```tsx
// src/app/layout.tsx
import 'shared/styles/global.css'
import type { Metadata } from 'next'
export const metadata: Metadata = {
title: 'App',
description: '',
}
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ru">
<head>
<link rel="preload" href="/sprites/icons.sprite.stack.svg" as="image" />
</head>
<body>{children}</body>
</html>
)
}
```
Локальные спрайты (если есть) подключаются аналогично в layout конкретной страницы или маршрута.
## Стандартный конфиг
Файл `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`.
## Дальше
- [Использование](/docs/applied/svg-sprites/svg-sprites-usage) — добавление иконок, компонент `<SvgSprite/>`, управление цветом.

56
projects/nextjs-style-guide/canons/applied/svg-sprites/svg-sprites-usage.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: Использование SVG-спрайтов
description: Как добавлять и использовать SVG-иконки в коде.
keywords: [svg, спрайт, sprite, иконка, icon, SvgSprite, превью, preview, цвет, color]
---
# Использование SVG-спрайтов
Как добавлять и использовать SVG-иконки в коде.
## Шаги
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);
}
```

97
projects/nextjs-style-guide/canons/applied/templates/templates-create.md Normal file
View File

@@ -0,0 +1,97 @@
---
title: Создание шаблонов генерации
description: "Структура шаблонов, синтаксис переменных и примеры."
keywords: [шаблоны, templates, .templates, syntax, переменные, kebabCase, pascalCase, scaffold]
---
<!-- @formatter:off -->
::: v-pre
# Создание шаблонов генерации
Структура шаблонов, синтаксис переменных и примеры.
## Структура шаблонов
Все шаблоны лежат в `.templates/` в корне проекта. Каждая папка — отдельный шаблон.
```text
.templates/
├── component/ # шаблон компонента
│ └── {{name.kebabCase}}/
│ ├── styles/
│ │ └── {{name.kebabCase}}.module.css
│ ├── types/
│ │ └── {{name.kebabCase}}-props.type.ts
│ ├── {{name.kebabCase}}.tsx
│ └── index.ts
└── store/ # шаблон Zustand стора
└── {{name.kebabCase}}/
├── {{name.kebabCase}}.store.ts
├── {{name.kebabCase}}.type.ts
└── index.ts
```
## Обязательный шаблон компонента
Перед созданием компонентов в проекте должен существовать шаблон `.templates/component`.
Если шаблона нет, компонент не создаётся вручную. Сначала создаётся шаблон компонента, затем компонент генерируется через [VS Code или CLI](/docs/applied/templates/templates-usage).
## Синтаксис шаблонов
### Переменные
Переменные работают в именах файлов/папок и внутри файлов:
```text
{{variable}}
```
Переменные могут быть любыми. `name` — дефолтная, подставляется генератором автоматически. Если реализация требует дополнительных параметров — можно использовать произвольные наборы переменных.
### Модификаторы
Модификаторы меняют регистр и формат записи переменной:
```text
{{name.pascalCase}} → MyButton
{{name.camelCase}} → myButton
{{name.kebabCase}} → my-button
{{name.snakeCase}} → my_button
{{name.screamingSnakeCase}} → MY_BUTTON
```
## Как создать новый шаблон
1. Создать папку в `.templates/` с именем шаблона (например `hook`).
2. Внутри разместить файлы и папки, используя `{{name}}` и модификаторы в именах и содержимом.
3. Шаблон сразу доступен и в расширении VS Code, и в CLI.
Пример — создание шаблона для хука:
```text
.templates/
└── hook/
└── {{name.kebabCase}}/
├── {{name.kebabCase}}.hook.ts
└── index.ts
```
```ts
// .templates/hook/{{name.kebabCase}}.hook.ts
export const {{name.camelCase}} = () => {
}
```
```ts
// .templates/hook/index.ts
export { {{name.camelCase}} } from './{{name.kebabCase}}.hook'
```
## Дальше
- [Использование](/docs/applied/templates/templates-usage) — генерация через VS Code плагин и CLI.
:::

32
projects/nextjs-style-guide/canons/applied/templates/templates-intro.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: Шаблоны генерации
description: "Что такое шаблоны кодогенерации и какие проблемы они решают."
---
# Шаблоны генерации
Что такое шаблоны кодогенерации и какие проблемы они решают.
## Проблема
Каждый новый модуль в проекте — компонент, стор, бизнес-модуль — требует однотипной структуры файлов и boilerplate-кода. Ручное создание приводит к трём проблемам:
- **Расхождения.** Разные разработчики создают модули по-разному: забывают `index.ts`, называют типы не по канону, пропускают стили.
- **Время.** Создание одного компонента с типами, стилями и экспортом — 5–10 минут рутины. За спринт набегают часы.
- **Ошибки копипасты.** Копирование существующего модуля и переименование — источник опечаток и забытых ссылок.
## Решение
Шаблоны кодогенерации — это папки с файлами-заготовками в `.templates/`. Вместо ручного создания файлов разработчик вызывает генератор, указывает имя — и получает готовый модуль со всей структурой, именами и boilerplate, подставленными автоматически.
Что дают шаблоны:
- **Единообразие.** Все модули одного типа идентичны по структуре. Канон живёт в шаблоне, а не в памяти разработчика.
- **Скорость.** Генерация модуля — одна команда. Остальное время — на бизнес-логику.
- **Согласованность с архитектурой.** Шаблоны учитывают SLM: правильные слои, сегменты, экспорты. Отклонение от стайлгайда требует осознанного усилия, а не случайного упущения.
## Состав раздела
- [Настройка](/docs/applied/templates/templates-setup) — первичная установка: скачивание стандартного набора шаблонов в проект.
- [Создание шаблонов](/docs/applied/templates/templates-create) — структура файлов, синтаксис переменных, примеры.
- [Использование](/docs/applied/templates/templates-usage) — генерация через VS Code плагин и CLI.

44
projects/nextjs-style-guide/canons/applied/templates/templates-setup.md Normal file
View File

@@ -0,0 +1,44 @@
---
title: Настройка шаблонов генерации
description: Первичная установка шаблонов кодогенерации в проект.
keywords: [шаблоны, templates, .templates, tiged, generator, генератор шаблонов, скачать шаблоны, scaffold]
---
# Настройка шаблонов генерации
Первичная установка шаблонов кодогенерации в проект.
## Установка
1. Проверить, что `.templates/` отсутствует (или согласовать перезапись, если папка уже есть).
2. Скачать папку из эталонного репозитория:
```bash
npx tiged git@gromlab.ru:templates/nextjs-template.git/.templates .templates
```
3. Если `tiged` падает в default-режиме (HTTP-tarball у Gitea) — повторить с явным git-режимом:
```bash
npx tiged --mode=git git@gromlab.ru:templates/nextjs-template.git/.templates .templates
```
4. Проверить генерацию:
```bash
npx @gromlab/create component test src/ui
```
После проверки — удалить тестовый модуль.
## Проверка установки
- В корне проекта есть папка `.templates/`.
- Внутри `.templates/` присутствуют стандартные шаблоны (или согласованный кастомный набор).
- Пробная генерация через `npx @gromlab/create ...` отрабатывает без ошибок.
## Дальше
- [Создание шаблонов](/docs/applied/templates/templates-create) — структура файлов, синтаксис переменных, примеры.
- [Использование](/docs/applied/templates/templates-usage) — генерация через VS Code плагин и CLI.

45
projects/nextjs-style-guide/canons/applied/templates/templates-usage.md Normal file
View File

@@ -0,0 +1,45 @@
---
title: Использование шаблонов генерации
description: Генерация файлов из шаблонов через VS Code плагин и CLI.
keywords: [шаблоны, templates, generate, VS Code, CLI, gromlab/create, npx, scaffold]
---
# Использование шаблонов генерации
Генерация файлов из шаблонов через VS Code плагин и CLI.
::: danger Ручное создание запрещено
Файлы, для которых есть шаблоны в `.templates/`, создаются только генератором. Ручное создание компонента, модуля, стора или другого шаблонного блока запрещено.
Если нужного шаблона нет, сначала создайте шаблон в `.templates/`, затем сгенерируйте код на его основе.
:::
## Через VS Code
Template File Generator | gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) — расширение для генерации файлов и папок из шаблонов через интерфейс редактора.
1. ПКМ на целевой папке в проводнике VS Code.
2. **Generate from template** → выбрать шаблон.
3. Ввести имя (например `button`) — расширение подставит его во все переменные `{{name}}`.
Расширение устанавливается разово на машину разработчика, не через проект.
## Через CLI
[@gromlab/create](https://www.npmjs.com/package/@gromlab/create) — CLI для генерации из тех же шаблонов. Используется через npx, глобальная установка не требуется.
```bash
npx @gromlab/create <шаблон> <имя> [путь]
```
Путь не обязателен — по умолчанию генерация происходит в текущую директорию.
| Команда | Что создаёт |
|---|---|
| `npx @gromlab/create component button` | Компонент в текущей папке |
| `npx @gromlab/create module auth src/business` | Бизнес-модуль |
| `npx @gromlab/create widget header src/widgets` | Виджет |
| `npx @gromlab/create layout admin src/layouts` | Layout |
| `npx @gromlab/create store auth src/business/auth/stores` | Стор |
CLI вызывается через `npx`, в `package.json` отдельно не добавляется.

88
projects/nextjs-style-guide/canons/applied/vscode.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: VS Code
description: Единые настройки редактора и расширений для команды.
---
# VS Code
Единые настройки редактора и расширений для команды.
## Структура `.vscode/`
```text
.vscode/
├── extensions.json # Рекомендуемые расширения
└── settings.json # Настройки редактора для проекта
```
Оба файла коммитятся в репозиторий.
## Расширения
Файл `.vscode/extensions.json` определяет список расширений, которые VS Code предложит установить при открытии проекта.
```json
// .vscode/extensions.json
{
"recommendations": [
"biomejs.biome",
"MyTemplateGenerator.mytemplategenerator",
"csstools.postcss"
]
}
```
| Расширение | Назначение |
|---|---|
| [Biome](https://marketplace.visualstudio.com/items?itemName=biomejs.biome) | Линтинг и форматирование кода. Заменяет ESLint и Prettier |
| Template File Generator \| gromlab ([Marketplace](https://marketplace.visualstudio.com/items?itemName=gromlab.vscode-templateFileGenerator), [Open VSX](https://open-vsx.org/extension/gromlab/vscode-templateFileGenerator)) | Генерация файлов и папок из шаблонов `.templates/` через контекстное меню |
| [PostCSS Language Support](https://marketplace.visualstudio.com/items?itemName=csstools.postcss) | Подсветка синтаксиса и автодополнение для PostCSS (`@custom-media`, `@nest` и др.) |
### Зачем это нужно
- Новый участник команды получает все нужные расширения одним кликом.
- Нет разночтений: все используют одинаковый форматтер и линтер.
- Расширения привязаны к проекту, а не к конкретному разработчику.
## Настройки редактора
Файл `.vscode/settings.json` переопределяет пользовательские настройки VS Code на уровне проекта.
```json
// .vscode/settings.json
{
"editor.defaultFormatter": "biomejs.biome",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.biome": "explicit",
"source.organizeImports.biome": "explicit"
},
"files.associations": {
"*.css": "postcss"
}
}
```
### Разбор настроек
| Настройка | Значение | Что делает |
|---|---|---|
| `editor.defaultFormatter` | `biomejs.biome` | Biome используется как единственный форматтер для всех файлов |
| `editor.formatOnSave` | `true` | Код автоматически форматируется при каждом сохранении |
| `codeActionsOnSave.source.fixAll.biome` | `explicit` | Biome автоматически применяет безопасные исправления при сохранении |
| `codeActionsOnSave.source.organizeImports.biome` | `explicit` | Импорты сортируются и группируются автоматически при сохранении |
| `files.associations` | `"*.css": "postcss"` | Все CSS-файлы открываются с подсветкой PostCSS вместо стандартного CSS |
### Зачем это нужно
- **Единый стиль кода** -- форматирование происходит автоматически, невозможно закоммитить неформатированный код.
- **Автофикс при сохранении** -- распространённые ошибки линтинга исправляются без ручного вмешательства.
- **Сортировка импортов** -- импорты всегда в одном порядке, без конфликтов при мерже.
- **PostCSS-подсветка** -- кастомные at-правила (`@custom-media`, `@define-mixin`) подсвечиваются корректно, а не как ошибки.
## Что не должно быть в `.vscode/`
Не коммитятся файлы, специфичные для конкретного разработчика:
- **Не коммитить**: отладочные конфигурации с локальными путями, персональные сниппеты, настройки тем оформления.
- **Коммитить**: только `extensions.json` и `settings.json` с общими для команды настройками.

153
projects/nextjs-style-guide/canons/basics/code-style.md Normal file
View File

@@ -0,0 +1,153 @@
---
title: Стиль кода
description: Как оформляется код в проекте.
---
# Стиль кода
Как оформляется код в проекте.
## Отступы
- 2 пробела (не табы).
## Длина строк
- Ориентироваться на 100 символов, но превышение допустимо, если строка читается легко.
- Переносить выражение на новые строки, когда строка становится плохо читаемой.
- Не переносить строку внутри строковых литералов без необходимости.
**Хорошо**
```ts
const config = createRequestConfig(
endpoint,
{
headers: {
'X-Request-Id': requestId,
'X-User-Id': userId,
},
params: {
page,
pageSize,
sort: 'createdAt',
},
},
timeoutMs,
);
```
**Плохо**
```ts
// Плохо: длинная строка с вложенными структурами плохо читается.
const config = createRequestConfig(endpoint, { headers: { 'X-Request-Id': requestId, 'X-User-Id': userId }, params: { page, pageSize, sort: 'createdAt' } }, timeoutMs);
```
## Кавычки
- В JavaScript/TypeScript использовать одинарные кавычки.
- В JSX/TSX для атрибутов использовать двойные кавычки.
- Шаблонные строки использовать только при интерполяции или многострочном тексте.
**Хорошо**
```ts
const label = 'Сохранить';
const title = `Привет, ${name}`;
```
```tsx
<input type="text" placeholder="Введите имя" />
```
**Плохо**
```ts
// Плохо: двойные кавычки в TS и конкатенация вместо шаблонной строки.
const label = "Сохранить";
const title = 'Привет, ' + name;
```
```tsx
// Плохо: одинарные кавычки в JSX-атрибутах.
<input type='text' placeholder='Введите имя' />
```
## Точки с запятой и запятые
- Допускаются упущения точки с запятой, если код остаётся читаемым и однозначным.
- В многострочных массивах, объектах и параметрах функции запятая в конце допускается, но не обязательна.
## Импорты
- В именованных импортах использовать пробелы внутри фигурных скобок.
- Типы импортировать через `import type`.
- `default` экспорт избегать, использовать именованные. `default` импорт допустим (например, стили CSS Modules, сторонние библиотеки).
- Избегать импорта всего модуля через `*`.
**Хорошо**
```ts
import { MyComponent } from 'MyComponent';
import type { User } from '../model/types';
import styles from './styles/button.module.css';
```
**Плохо**
```ts
// Плохо: отсутствие пробелов в именованном импорте.
import type {User} from '../model/types';
// Плохо: default экспорт.
export default MyComponent;
```
## Ранние возвраты (early return)
- Использовать ранние возвраты для упрощения чтения.
- Избегать `else` после `return`.
**Хорошо**
```ts
const getName = (user?: { name: string }) => {
if (!user) {
return 'Гость';
}
return user.name;
};
```
**Плохо**
```ts
// Плохо: лишний else после return усложняет чтение.
const getName = (user?: { name: string }) => {
if (user) {
return user.name;
} else {
return 'Гость';
}
};
```
## Форматирование объектов и массивов
- В многострочных объектах каждое свойство на новой строке.
- В многострочных массивах каждый элемент на новой строке.
- Объекты и массивы можно писать в одну строку, если длина строки не превышает 100 символов.
- В однострочных объектах и массивах использовать пробелы после запятых.
**Хорошо**
```ts
const roles = ['admin', 'editor', 'viewer'];
const options = { id: 1, name: 'User' };
const config = {
url: '/api/users',
method: 'GET',
params: { page: 1, pageSize: 20 },
};
```
**Плохо**
```ts
// Плохо: нет пробелов после запятых и объект слишком длинный для одной строки.
const roles = ['admin','editor','viewer'];
const options = { id: 1,name: 'User' };
const config = { url: '/api/users', method: 'GET', params: { page: 1, pageSize: 20 } };
```

134
projects/nextjs-style-guide/canons/basics/documentation.md Normal file
View File

@@ -0,0 +1,134 @@
---
title: Документирование
description: Что и как документировать в коде.
---
# Документирование
Что и как документировать в коде.
## Общие правила
- Документировать публичные функции, компоненты, типы, интерфейсы и enum.
- Не документировать очевидное — если название говорит само за себя, комментарий не нужен.
- Не документировать параметры, возвращаемые значения и типы пропсов — они видны из сигнатуры.
- Описание через пользу и назначение, а не через внутреннюю реализацию.
- Описание завершается точкой.
## Функции
Для документирования функций используется шаблон. Описание механики опционально —
добавляется когда логика нетривиальна.
**Шаблон**
```ts
/**
* <Что делает функция в 1 строке>.
*
* <Опционально: описание сложной механики или важных нюансов>.
*/
```
**Хорошо**
```ts
/**
* Форматирует цену с символом валюты.
*/
export const formatPrice = (value: number): string => { ... }
/**
* Рекурсивно собирает дерево категорий из плоского списка.
*
* Группирует элементы по parentId, начиная с корневых (parentId = null).
* Категории без родителя попадают в корень дерева.
*/
export const buildCategoryTree = (categories: Category[]): CategoryTree[] => { ... }
```
**Плохо**
```ts
// Плохо: дублирует сигнатуру.
/**
* @param value - число
* @returns строка с ценой
*/
```
## Компоненты
Компонент описывает своё **назначение** и **сценарии применения** — это помогает понять, когда и где его использовать, без необходимости читать реализацию.
**Шаблон**
```ts
/**
* <Назначение компонента в 1 строке>.
*
* Используется для:
* - <сценарий 1>
* - <сценарий 2>
* - <сценарий 3>
*/
```
**Хорошо**
```tsx
/**
* Контейнер с адаптивной максимальной шириной.
*
* Используется для:
* - обёртки контента страниц с ограничением ширины
* - центрирования блоков в лейауте
*/
export const Container = (props: ContainerProps) => { ... }
```
**Плохо**
```tsx
// Плохо: описывает реализацию, а не назначение.
/**
* Рендерит div с className и htmlAttr.
*/
// Плохо: нет описания вообще.
export const Container = (props: ContainerProps) => { ... }
```
## Типы, интерфейсы, enum
Документируются назначение сущности и каждое её поле.
**Хорошо**
```ts
/**
* Фильтры списка задач.
*/
export enum TodoFilter {
/** Все задачи. */
ALL = 'all',
/** Только активные. */
ACTIVE = 'active',
/** Только завершённые. */
COMPLETED = 'completed',
}
/**
* Задача пользователя.
*/
export interface TodoItem {
/** Уникальный идентификатор задачи. */
id: string;
/** Текст задачи. */
text: string;
/** Статус выполнения. */
completed: boolean;
}
```
**Плохо**
```ts
// Плохо: описывает очевидное.
export interface TodoItem {
/** id — это id */
id: string;
}
```

146
projects/nextjs-style-guide/canons/basics/naming.md Normal file
View File

@@ -0,0 +1,146 @@
---
title: Именование
description: Как называть переменные, файлы и прочие сущности в коде.
---
# Именование
Как называть переменные, файлы и прочие сущности в коде.
## Базовые правила
| Что | Рекомендуется |
| ---------------- | ---------------------- |
| Папки | `kebab-case` |
| Файлы | `kebab-case` |
| Переменные | `camelCase` |
| Константы | `SCREAMING_SNAKE_CASE` |
| Классы | `PascalCase` |
| React-компоненты | `PascalCase` |
| Хуки | `useSomething` |
| CSS классы | `camelCase` |
| Ключи enum | `SCREAMING_SNAKE_CASE` |
## Именование файлов
Суффикс обозначает роль или тип файла. Пишется в единственном числе.
Формат: `name.<suffix>.ts`.
**Хуки**
- `use-name.hook.ts` — файл хука, функция именуется `useName`
**Логика**
- `.store.ts` — стор
- `.service.ts` — сервис
**Корневые компоненты слоёв**
- `.screen.tsx` — корневой компонент screen-модуля: `screens/profile/profile.screen.tsx`, компонент `ProfileScreen`
- `.layout.tsx` — корневой компонент layout-модуля: `layouts/main/main.layout.tsx`, компонент `MainLayout`
Обычные и вложенные модули не получают суффикс слоя: `ui/button/button.tsx`, `screens/profile/parts/activity-feed/activity-feed.tsx`.
**Типы и контракты**
- `.type.ts` — типы и интерфейсы
- `.interface.ts` — интерфейсы
- `.enum.ts` — enum
- `.dto.ts` — внешние DTO
- `.schema.ts` — схемы валидации
- `.constant.ts` — константы
- `.config.ts` — конфигурация
**Утилиты**
- `.util.ts` — утилиты
- `.helper.ts` — вспомогательные функции
- `.lib.ts` — библиотечный код
**Тесты**
- `.test.ts` — тесты
- `.mock.ts` — моки
**Хорошо**
```text
business/
└── auth-by-email/
├── ui/
│ └── login-form.tsx
├── hooks/
│ └── use-auth.hook.ts
├── stores/
│ └── auth.store.ts
├── types/
│ └── auth.type.ts
├── auth-by-email.tsx
└── index.ts
```
**Плохо**
```text
business/
└── authByEmail/
├── LoginForm.tsx
├── useAuth.ts
├── authStore.ts
└── index.ts
```
## Булевы значения
- Использовать префиксы `is`, `has`, `can`, `should`.
**Хорошо**
```ts
const isReady = true;
const hasAccess = false;
const canSubmit = true;
const shouldRedirect = false;
```
**Плохо**
```ts
// Плохо: неясное булево значение без префикса.
const ready = true;
const access = false;
const submit = true;
```
## События и обработчики
- Обработчики начинать с `handle`.
- События и колбэки начинать с `on`.
**Хорошо**
```ts
const handleSubmit = () => { ... };
const onSubmit = () => { ... };
```
**Плохо**
```ts
// Плохо: неочевидное назначение имени.
const submitClick = () => { ... };
```
## Коллекции
- Для массивов использовать имена во множественном числе.
- Для словарей/мап — использовать суффиксы `ById`, `Map`, `Dict`.
**Хорошо**
```ts
const users = [];
const usersById = {} as Record<string, User>;
const userIds = ['u1', 'u2'];
const ordersMap = new Map<string, Order>();
const featureFlagsDict = { beta: true, legacy: false } as Record<string, boolean>;
```
**Плохо**
```ts
// Плохо: имя не отражает, что это коллекция.
const user = [];
// Плохо: словарь назван как массив.
const usersMap = [];
// Плохо: по имени непонятно, что это словарь.
const users = {} as Record<string, User>;
```

42
projects/nextjs-style-guide/canons/basics/tech-stack.md Normal file
View File

@@ -0,0 +1,42 @@
---
title: Технологии и библиотеки
description: Какие библиотеки и инструменты используются в проекте.
---
# Технологии и библиотеки
Какие библиотеки и инструменты используются в проекте.
## Что используем
### Стек
- `React` / `TypeScript` — основной стек для UI и приложения.
- `Next.js` — для продуктовых сайтов.
### Архитектура
- `SLM Design` — собственная модульная архитектура проекта. Подробнее в разделе [Архитектура](/docs/basics/architecture/).
### UI компоненты
- `Mantine UI` — базовые UI-компоненты.
### Работа с данными (API)
- `@gromlab/api-codegen` — генерация API‑клиентов и типов.
- `SWR` — получение, кеширование, ревалидация, дедубликация.
- `SWR (useSWRSubscription)` — сокеты, реалтайм подписки.
### Store
- `Zustand` — глобальное состояние.
### Локализация
- `i18next (i18n)` — локализация всех пользовательских текстов.
### Тестирование
- `Vitest` — тестирование.
### Стили
- `PostCSS Modules` — изоляция стилей.
- `Mobile First` — подход к адаптивной верстке.
- `clsx` — конкатенация CSS‑классов.
### Генерация
- `@gromlab/create` — шаблонизатор для создания слоёв и других файлов из шаблонов.

62
projects/nextjs-style-guide/canons/basics/typing.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: Типизация
description: Как типизируется код в проекте.
---
# Типизация
Как типизируется код в проекте.
## Общие правила
- Указывать типы для параметров компонентов и параметров функций.
- Предпочитать `type` для описания сущностей и `interface` для расширяемых контрактов.
- Избегать `any` и `unknown` без необходимости.
- Не использовать `ts-ignore`, кроме крайних случаев с явным комментарием причины.
## React-компоненты
- Пропсы компонента типизировать через отдельный `Props`.
- Возвращаемый тип компонента не указывать: TypeScript корректно выводит JSX-результат, а явный `ReactElement` сужает допустимые варианты возврата.
## Функции
- Для публичных функций указывать возвращаемый тип.
- Не полагаться на неявный вывод для важных API.
**Хорошо**
```ts
export const formatPrice = (value: number): string => {
return `${value} ₽`;
};
```
**Плохо**
```ts
// Плохо: нет явного возвращаемого типа.
export const formatPrice = (value: number) => {
return `${value} ₽`;
};
```
## Работа с any/unknown
- `any` использовать только для временных заглушек.
- `unknown` сужать через проверки перед использованием.
**Хорошо**
```ts
const parse = (value: unknown): string => {
if (typeof value === 'string') {
return value;
}
return '';
};
```
**Плохо**
```ts
// Плохо: any отключает проверку типов.
const parse = (value: any) => value;
```

79
projects/nextjs-style-guide/canons/index.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: NextJS Style Guide
description: Практический стайлгайд для разработки frontend-приложений на Next.js и TypeScript.
---
# NextJS Style Guide
Практический стайлгайд для разработки frontend-приложений на Next.js и TypeScript.
## Использование
**Для AI-агентов:**
- [llms.txt](/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
- [llms-full.txt](/llms-full.txt) — Вся документация одним файлом.
**Для проекта:**
- [nextjs-style-guide.zip](/nextjs-style-guide/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
## Структура документации
### Подсказки
[Подсказки](/docs/workflow) — короткие ответы на типовые вопросы и решения для спорных ситуаций.
### Базовые правила
**Каким должен быть код** — стандарты, не привязанные к конкретной технологии.
| Раздел | Отвечает на вопрос |
|--------|-------------------|
| Технологии и библиотеки | Какой стек используем? |
| Именование | Как называть файлы, переменные, компоненты, хуки? |
| SLM Design | Что такое SLM и зачем она нужна? |
| Архитектура: Слои | Какие слои есть и как между ними устроены зависимости? |
| Архитектура: Модули | Что такое модуль и как он устроен? |
| Архитектура: Сегменты | Какие сегменты есть внутри модуля? |
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
| Документирование | Как писать JSDoc: что документировать, а что нет? |
| Типизация | Как типизировать: type vs interface, any/unknown? |
### Настройка
**Как сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры.
| Раздел | Отвечает на вопрос |
|--------|-------------------|
| Создание проекта из шаблона | Как начать проект из готового шаблона? |
| Создание проекта вручную | Как поднять проект с нуля без шаблона? |
| Чистая установка Next.js | Как поставить голый Next.js под дальнейшую сборку? |
| Алиасы импортов | Как настроить алиасы импортов? |
| Biome | Как настроить линтер и форматтер? |
| PostCSS | Какие плагины PostCSS нужны и как их настроить? |
| Стили | Как подключить базовые стили и токены? |
| SVG-спрайты | Как подключить генерацию SVG-спрайтов? |
| Шаблоны генерации | Как подключить шаблоны для кодогенерации? |
| VS Code | Как настроить редактор для проекта? |
### Использование
**Как это устроено и как этим пользоваться** — структура, примеры и правила для конкретных областей.
| Раздел | Отвечает на вопрос |
|--------|-------------------|
| Структура проекта | Как организованы папки и файлы по SLM? |
| Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
| Файлы роутинга | Как описывать layout, page, loading, error, not-found? |
| REST-клиент | Как настроить клиент внешнего REST API? |
| Получение данных | Как выбрать способ получения данных под рендер страницы? |
| Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
| Стили | Как писать CSS: вложенность, медиа, токены? |
| SVG-спрайты | Как использовать SVG-спрайты в коде? |
| Изображения | _(не заполнен)_ |
| Видео | _(не заполнен)_ |
| Stores | _(не заполнен)_ |
| Хуки | _(не заполнен)_ |
| Шрифты | _(не заполнен)_ |
| Локализация | _(не заполнен)_ |

8
projects/nextjs-style-guide/canons/workflow.md Normal file
View File

@@ -0,0 +1,8 @@
---
title: Подсказки
description: Короткие ответы на типовые вопросы и решения для спорных ситуаций.
---
# Подсказки
Короткие ответы на типовые вопросы и решения для спорных ситуаций.

28
projects/nextjs-style-guide/docs/.vitepress/config.ts Normal file
View File

@@ -0,0 +1,28 @@
import { defineConfig } from 'vitepress';
import taskLists from 'markdown-it-task-lists';
import llmstxt from 'vitepress-plugin-llms';
import { themeSyncHead } from '../../../_shared/docs/vitepress/themeHead';
import { sidebar, site } from '../docs.config';
export default defineConfig({
title: site.title,
description: site.description,
base: site.base,
outDir: site.outDir,
srcDir: 'content',
cleanUrls: true,
ignoreDeadLinks: [/^\/slm-design\//],
head: [...themeSyncHead],
vite: {
plugins: [llmstxt()],
},
markdown: {
config(md) {
md.use(taskLists);
},
},
themeConfig: {
sidebar,
socialLinks: [],
},
});

1
projects/nextjs-style-guide/docs/.vitepress/theme/index.ts Normal file
View File

@@ -0,0 +1 @@
export { default } from '../../../../_shared/docs/vitepress/theme';

201
projects/nextjs-style-guide/docs/docs.config.ts Normal file
View File

@@ -0,0 +1,201 @@
export const site = {
title: 'NextJS Style Guide',
description: 'Практический стайлгайд для разработки frontend-приложений на Next.js и TypeScript',
base: '/nextjs-style-guide/',
outDir: '../../../public/nextjs-style-guide',
};
/**
* Карта монтирования исходных канонов в VitePress-документацию.
*
* SLM-разделы берутся из проекта `slm-design`, чтобы NextJS-гайд не содержал
* собственных дублей архитектурного канона.
*/
export const mounts = [
{ target: 'index.md', source: 'canons/index.md' },
{ target: 'workflow.md', source: 'canons/workflow.md' },
{ target: 'slm-design/architecture/index.md', source: '../slm-design/canons/architecture/index.md' },
{ target: 'slm-design/architecture/layers.md', source: '../slm-design/canons/architecture/layers.md' },
{ target: 'slm-design/architecture/modules.md', source: '../slm-design/canons/architecture/modules.md' },
{ target: 'slm-design/architecture/segments.md', source: '../slm-design/canons/architecture/segments.md' },
{ target: 'slm-design/architecture/monorepo.md', source: '../slm-design/canons/architecture/monorepo.md' },
{ target: 'slm-design/examples/react/factory.md', source: '../slm-design/canons/examples/react/factory.md' },
{ target: 'slm-design/examples/react/factory-composition.md', source: '../slm-design/canons/examples/react/factory-composition.md' },
{ target: 'slm-design/examples/react/composition-provider.md', source: '../slm-design/canons/examples/react/composition-provider.md' },
{ target: 'basics/tech-stack.md', source: 'canons/basics/tech-stack.md' },
{ target: 'basics/naming.md', source: 'canons/basics/naming.md' },
{ target: 'basics/code-style.md', source: 'canons/basics/code-style.md' },
{ target: 'basics/documentation.md', source: 'canons/basics/documentation.md' },
{ target: 'basics/typing.md', source: 'canons/basics/typing.md' },
{ target: 'applied/creating-project/from-template.md', source: 'canons/applied/creating-project/from-template.md' },
{ target: 'applied/creating-project/manual.md', source: 'canons/applied/creating-project/manual.md' },
{ target: 'applied/creating-project/nextjs.md', source: 'canons/applied/creating-project/nextjs.md' },
{ target: 'applied/project-structure.md', source: 'canons/applied/project-structure.md' },
{ target: 'applied/page-level.md', source: 'canons/applied/page-level.md' },
{ target: 'applied/component.md', source: 'canons/applied/component.md' },
{ target: 'applied/module.md', source: 'canons/applied/module.md' },
{ target: 'applied/rest-client/index.md', source: 'canons/applied/rest-client/index.md' },
{ target: 'applied/rest-client/setup/index.md', source: 'canons/applied/rest-client/setup/index.md' },
{ target: 'applied/rest-client/setup/auto.md', source: 'canons/applied/rest-client/setup/auto.md' },
{ target: 'applied/rest-client/setup/manual.md', source: 'canons/applied/rest-client/setup/manual.md' },
{ target: 'applied/rest-client/setup/hooks.md', source: 'canons/applied/rest-client/setup/hooks.md' },
{ target: 'applied/rest-client/usage.md', source: 'canons/applied/rest-client/usage.md' },
{ target: 'applied/data-fetch/index.md', source: 'canons/applied/data-fetch/index.md' },
{ target: 'applied/data-fetch/server-await.md', source: 'canons/applied/data-fetch/server-await.md' },
{ target: 'applied/data-fetch/parallel-server-requests.md', source: 'canons/applied/data-fetch/parallel-server-requests.md' },
{ target: 'applied/data-fetch/pass-promise-down.md', source: 'canons/applied/data-fetch/pass-promise-down.md' },
{ target: 'applied/data-fetch/client-hooks-initial-data.md', source: 'canons/applied/data-fetch/client-hooks-initial-data.md' },
{ target: 'applied/data-fetch/client-get-hook.md', source: 'canons/applied/data-fetch/client-get-hook.md' },
{ target: 'applied/data-fetch/business-composition.md', source: 'canons/applied/data-fetch/business-composition.md' },
{ target: 'applied/styles/styles-setup.md', source: 'canons/applied/styles/styles-setup.md' },
{ target: 'applied/styles/styles-usage.md', source: 'canons/applied/styles/styles-usage.md' },
{ target: 'applied/svg-sprites/svg-sprites-intro.md', source: 'canons/applied/svg-sprites/svg-sprites-intro.md' },
{ target: 'applied/svg-sprites/svg-sprites-setup.md', source: 'canons/applied/svg-sprites/svg-sprites-setup.md' },
{ target: 'applied/svg-sprites/svg-sprites-usage.md', source: 'canons/applied/svg-sprites/svg-sprites-usage.md' },
{ target: 'applied/images.md', source: 'canons/applied/images.md' },
{ target: 'applied/fonts.md', source: 'canons/applied/fonts.md' },
{ target: 'applied/aliases.md', source: 'canons/applied/aliases.md' },
{ target: 'applied/templates/templates-intro.md', source: 'canons/applied/templates/templates-intro.md' },
{ target: 'applied/templates/templates-setup.md', source: 'canons/applied/templates/templates-setup.md' },
{ target: 'applied/templates/templates-create.md', source: 'canons/applied/templates/templates-create.md' },
{ target: 'applied/templates/templates-usage.md', source: 'canons/applied/templates/templates-usage.md' },
{ target: 'applied/biome.md', source: 'canons/applied/biome.md' },
{ target: 'applied/postcss.md', source: 'canons/applied/postcss.md' },
{ target: 'applied/vscode.md', source: 'canons/applied/vscode.md' },
{ target: 'applied/localization.md', source: 'canons/applied/localization.md' },
{ target: 'applied/stores.md', source: 'canons/applied/stores.md' },
];
export const routeRewrites = [
{ from: '/docs/basics/architecture', to: '/slm-design/architecture' },
{ from: '/architecture', to: '/slm-design/architecture' },
{ from: '/examples', to: '/slm-design/examples' },
];
export const sidebar = [
{
text: 'Подсказки',
link: '/workflow',
},
{
text: 'Архитектура',
items: [
{
text: 'Спецификация SLM',
items: [
{ text: 'Обзор', link: '/slm-design/architecture/' },
{ text: 'Слои', link: '/slm-design/architecture/layers' },
{ text: 'Модули', link: '/slm-design/architecture/modules' },
{ text: 'Сегменты', link: '/slm-design/architecture/segments' },
{ text: 'Монорепозитории', link: '/slm-design/architecture/monorepo' },
],
},
{
text: 'Примеры',
collapsed: true,
items: [
{ text: 'Создание фабрики', link: '/slm-design/examples/react/factory' },
{ text: 'Композиция фабрик', link: '/slm-design/examples/react/factory-composition' },
{ text: 'Композиция через Provider', link: '/slm-design/examples/react/composition-provider' },
],
},
],
},
{
text: 'Базовые правила',
items: [
{ text: 'Технологии и библиотеки', link: '/basics/tech-stack' },
{ text: 'Именование', link: '/basics/naming' },
{ text: 'Стиль кода', link: '/basics/code-style' },
{ text: 'Документирование', link: '/basics/documentation' },
{ text: 'Типизация', link: '/basics/typing' },
],
},
{
text: 'Прикладные разделы',
items: [
{
text: 'Создание проекта',
collapsed: true,
items: [
{ text: 'Из шаблона', link: '/applied/creating-project/from-template' },
{ text: 'По гайду вручную', link: '/applied/creating-project/manual' },
{ text: 'Чистый Next.js', link: '/applied/creating-project/nextjs' },
],
},
{ text: 'Структура проекта', link: '/applied/project-structure' },
{ text: 'Страницы', link: '/applied/page-level' },
{ text: 'Компонент', link: '/applied/component' },
{ text: 'Модуль', link: '/applied/module' },
{
text: 'REST-клиент',
collapsed: true,
items: [
{ text: 'Введение', link: '/applied/rest-client/' },
{
text: 'Настройка',
collapsed: true,
items: [
{ text: 'Обзор', link: '/applied/rest-client/setup/' },
{ text: 'Автогенерация из OpenAPI', link: '/applied/rest-client/setup/auto' },
{ text: 'Ручное создание', link: '/applied/rest-client/setup/manual' },
{ text: 'GET-хуки REST-клиента', link: '/applied/rest-client/setup/hooks' },
],
},
{ text: 'Использование', link: '/applied/rest-client/usage' },
],
},
{
text: 'Получение данных',
collapsed: true,
items: [
{ text: 'Обзор', link: '/applied/data-fetch/' },
{ text: 'Серверный await', link: '/applied/data-fetch/server-await' },
{ text: 'Параллельные серверные запросы', link: '/applied/data-fetch/parallel-server-requests' },
{ text: 'Передача промиса ниже', link: '/applied/data-fetch/pass-promise-down' },
{ text: 'Начальные данные для клиентских хуков', link: '/applied/data-fetch/client-hooks-initial-data' },
{ text: 'Клиентский GET-хук', link: '/applied/data-fetch/client-get-hook' },
{ text: 'Business-композиция', link: '/applied/data-fetch/business-composition' },
],
},
{
text: 'Стили',
collapsed: true,
items: [
{ text: 'Настройка', link: '/applied/styles/styles-setup' },
{ text: 'Использование', link: '/applied/styles/styles-usage' },
],
},
{
text: 'SVG-спрайты',
collapsed: true,
items: [
{ text: 'Введение', link: '/applied/svg-sprites/svg-sprites-intro' },
{ text: 'Настройка', link: '/applied/svg-sprites/svg-sprites-setup' },
{ text: 'Использование', link: '/applied/svg-sprites/svg-sprites-usage' },
],
},
{ text: 'Изображения', link: '/applied/images' },
{ text: 'Шрифты', link: '/applied/fonts' },
{ text: 'Алиасы импортов', link: '/applied/aliases' },
{
text: 'Шаблоны генерации',
collapsed: true,
items: [
{ text: 'Введение', link: '/applied/templates/templates-intro' },
{ text: 'Настройка', link: '/applied/templates/templates-setup' },
{ text: 'Создание шаблонов', link: '/applied/templates/templates-create' },
{ text: 'Использование', link: '/applied/templates/templates-usage' },
],
},
{ text: 'Biome', link: '/applied/biome' },
{ text: 'PostCSS', link: '/applied/postcss' },
{ text: 'VS Code', link: '/applied/vscode' },
{ text: 'Локализация', link: '/applied/localization' },
{ text: 'Stores', link: '/applied/stores' },
],
},
];

5
projects/nextjs-style-guide/project.config.ts Normal file
View File

@@ -0,0 +1,5 @@
export default {
slug: 'nextjs-style-guide',
docsDir: 'docs',
archive: true,
} as const;

0
projects/nextjs-style-guide/scripts/.gitkeep Normal file
View File

20
projects/slm-design/build.ts Normal file
View File

@@ -0,0 +1,20 @@
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { prepareDocs } from '../_shared/lib/prepare-docs';
import { run } from '../_shared/lib/run';
import { writeZipFromDirectory } from '../_shared/lib/zip';
import config from './project.config';
const projectDir = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(projectDir, '../..');
const docsDir = path.join(projectDir, config.docsDir);
await prepareDocs(projectDir, config);
run('npx', ['vitepress', 'build', docsDir], rootDir);
if (config.archive) {
const zipPath = path.join(rootDir, 'public', config.slug, `${config.slug}.zip`);
writeZipFromDirectory(path.join(docsDir, 'content'), zipPath, config.slug);
console.log(`Собран ${path.relative(rootDir, zipPath)}`);
}

114
projects/slm-design/canons/architecture/index.md Normal file
View File

@@ -0,0 +1,114 @@
---
title: SLM Design
description: Назначение архитектуры, ключевые принципы и карта разделов документации
---
# SLM Design
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
## Разделы спецификации
Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
- [Слои](/architecture/layers) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
- [Модули](/architecture/modules) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
- [Сегменты](/architecture/segments) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
- [Монорепозитории](/architecture/monorepo) — применение SLM в `apps/` и `packages/`, правила выноса общих слоёв и ограничения для business.
Рекомендуемый порядок чтения: обзор → слои → модули → сегменты → монорепозитории.
## Преимущества
### Вертикальная организация домена
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
### Dependency Injection без фреймворков
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
### Разделение ответственности без перегрузки слоёв
Сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
### Горизонтальная инкапсуляция
Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
### Колокация по умолчанию
Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
### Явное разделение каркаса и контента
Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
### Масштабирование через группировку
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
### Адаптация к монорепозиториям
SLM применяется внутри каждого приложения, а `packages/*` используются только для общего кода из слоёв `ui`, `infra` и `shared`. Бизнес-домены остаются внутри приложений, чтобы не размывать продуктовые границы.
## Происхождение
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/
│
├── infra/
│ ├── theme/
│ ├── i18n/
│ ├── backend-api/
│ └── logger/
│
├── ui/
│ ├── button/
│ ├── input/
│ ├── modal/
│ ├── toast/
│ └── dropdown/
│
└── shared/
├── lib/
├── types/
└── styles/
```
## Принципы
- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.

254
projects/slm-design/canons/architecture/layers.md Normal file
View File

@@ -0,0 +1,254 @@
---
title: Слои
description: Иерархия слоёв от app до shared, правила зависимостей и зона ответственности каждого слоя
---
# Слои
Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом.
## Определение
**Слой — уровень организации кода внутри `src/`. Каждый слой отвечает за свою область (каркас страницы, бизнес-логика, UI-кит) и задаёт правила для кода внутри: направление импортов, именование, допустимые связи между модулями.**
## Группы слоёв
Слои делятся на три группы:
| Группа | Слои | Описание |
|--------|------|----------|
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
| Ядро | `business`, `infra`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
## Направление зависимостей
Любой импорт между модулями — только через публичный API.
```
app → [ layouts | screens ] → widgets → business → infra → ui → shared
```
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
- Модули одного слоя в группе «Композиция» изолированы друг от друга
- Модули одного слоя `infra` и `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 и сервисами.
Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`. Каждый бизнес-модуль создаёт публичный runtime API через фабрику в корне. Cross-domain зависимости: runtime — через аргументы фабрики, типы — напрямую через `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/
```
### Требования
- Один модуль = один бизнес-домен
- Циклические зависимости между доменами запрещены
- Публичный runtime API — через фабрику в корне модуля (`{name}.factory.ts`). `index.ts` экспортирует только фабрику и type-only экспорты
- Импорт runtime-кода между доменами — через фабрику. `import type` — напрямую
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
## Слой infra
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
Слой входит в группу «Ядро». Импортирует `infra/`, `ui/`, `shared/`.
Отличие от `shared/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
```text
src/infra/
├── theme/
├── i18n/
├── backend-api/
├── maps-api/
├── logger/
├── feature-flags/
└── realtime/
```
### Требования
- Один модуль = один техсервис
- Импортирует `infra/`, `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
Общие ресурсы: утилиты, хелперы, стили, конфиги. Не знает о бизнес-домене.
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
Отличие от `infra/`: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
```text
src/shared/
├── lib/
├── types/
├── styles/
└── sprites/
```
### Требования
- Не имеет runtime-состояния

215
projects/slm-design/canons/architecture/modules.md Normal file
View File

@@ -0,0 +1,215 @@
---
title: Модули
description: Структура модуля, типы (UI, бизнес, инфра), публичный API, отличие модуля от компонента
---
# Модули
Раздел описывает модуль как границу ответственности в SLM: что считается модулем, что такое компонент внутри модуля и как модуль взаимодействует с остальным кодом.
## Определение
**Модуль — минимальная архитектурная единица SLM. Он живёт на одном из слоёв, владеет конкретной областью ответственности и предоставляет наружу только публичный API.**
Модуль может содержать всё, что нужно этой области: компоненты, вложенные модули, хуки, сторы, сервисы, типы, стили, конфиги и утилиты. Набор сегментов не фиксирован — модуль включает только то, что реально нужно.
Модуль не обязан быть UI-блоком. Это может быть страница, виджет, бизнес-домен, инфраструктурный сервис или UI-kit сущность.
Главная граница модуля — не папка, а ответственность.
## Компонент
**Компонент — презентационная единица модуля, которая находится только в `ui/` своего родительского модуля и отвечает за отображение части интерфейса.**
Компонент не является архитектурной единицей: он не владеет сценарием, зависимостями, данными или внутренней структурой. Он работает только внутри границы родительского модуля.
> Компонент отображает. Модуль организует.
Компонент не может:
- Импортировать код проекта за пределами родительского модуля.
- Владеть архитектурными зависимостями.
- Содержать любые компоненты.
- Содержать любые модули.
- Делать внешние запросы.
- Самостоятельно получать данные.
- Выбирать источник данных.
- Композировать данные.
- Вызывать сценарные хуки.
- Оркестрировать сценарий.
- Композировать модули.
- Решать, как устроен процесс.
- Содержать бизнес-логику.
- Содержать сценарную логику.
Если компоненту требуется что-то из этого списка, он перестаёт быть компонентом и должен быть оформлен как модуль.
```text
auth/
├── ui/
│ └── logout-button/
│ ├── logout-button.tsx
│ ├── styles/
│ │ └── logout-button.module.css
│ ├── types/
│ │ └── logout-button-props.type.ts
│ └── index.ts
└── index.ts
```
## Что считается модулем
Модулем считается папка, которая представляет самостоятельную область ответственности и имеет публичную границу.
Примеры модулей:
- `screens/home/` — модуль страницы.
- `widgets/page-heading/` — модуль виджета.
- `business/auth/` — модуль бизнес-домена.
- `infra/theme/` — модуль инфраструктурного сервиса.
- `ui/button/` — модуль UI-kit сущности.
- `screens/home/parts/hero-section/` — вложенный модуль страницы.
Не считаются модулями:
- `ui/`, `parts/`, `hooks/`, `types/`, `styles/`, `config/` — это сегменты.
- `screens/shop/`, `business/commerce/` — это группы, если в них нет `index.ts`.
- `screens/home/ui/user-card/` — это компонент, если он находится в `ui/` и соблюдает ограничения компонента.
## Типы модулей
Тип модуля определяет обязательный корневой файл и стартовую структуру.
### UI-модуль
Модуль строится вокруг основного UI-компонента и обязан иметь основной `.tsx` файл в корне:
```text
header/
├── header.tsx
└── index.ts
```
`ui/` внутри такого модуля используется только для компонентов, которые помогают корневому `.tsx` файлу.
### Бизнес-модуль
Бизнес-модуль — модуль, который строится вокруг публичного runtime API.
Бизнес-модуль обязан иметь фабрику в корне:
```text
auth/
├── auth.factory.ts
├── index.ts
└── types/
```
Фабрика возвращает публичный runtime API модуля.
### Инфраструктурный модуль
Инфраструктурный модуль — модуль, который строится вокруг технического сервиса или интеграции.
Инфраструктурный модуль не обязан иметь фиксированный корневой файл. Его структура определяется природой сервиса.
```text
theme/
├── index.ts
├── config/
├── hooks/
├── styles/
└── ui/
```
```text
backend-api/
├── backend-api.client.ts
├── config/
├── types/
└── index.ts
```
## Структура
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль включает только те части, которые нужны его ответственности.
```text
{module-name}/
├── {module-name}.factory.ts # фабрика (для business-модулей)
├── {module-name}.tsx # корневой файл модуля (опционален)
├── ui/ # компоненты модуля
├── parts/ # вложенные модули
├── hooks/ # хуки
├── stores/ # сторы состояния
├── services/ # внешние источники данных
├── mappers/ # трансформация данных между форматами
├── types/ # типы
├── styles/ # стили
├── lib/ # утилиты модуля
├── config/ # константы и конфигурация
└── index.ts # публичный API
```
Подробное описание сегментов — в разделе [Сегменты](/architecture/segments).
## Публичный API
Внешний код импортирует модуль только через публичный API.
```ts
// Хорошо
import { customerFactory } from '@/business/customer'
import type { Customer } from '@/business/customer'
```
```ts
// Плохо
import { validateToken } from '@/business/auth/lib/tokens'
```
`index.ts` модуля не обязан экспортировать всё содержимое. Он экспортирует только то, что действительно нужно снаружи.
Внутренние сегменты модуля остаются деталями реализации.
Business-модуль экспортирует из `index.ts` только фабрику и type-only экспорты. Хуки, компоненты, сервисы, мапперы и утилиты напрямую из `index.ts` не экспортируются — они доступны через API, который возвращает фабрика.
```ts
// business/customer/index.ts
export { customerFactory } from './customer.factory'
export type { Customer } from './types/customer.type'
export type { CustomerApi } from './types/customer-api.type'
export type { CustomerDeps } from './types/customer-deps.type'
export type { CustomerFactory } from './types/customer-factory.type'
```
## Фабрика
Business-модуль всегда экспортирует фабрику. Фабрика лежит в корне модуля (`{name}.factory.ts`), типизируется через `{Name}Factory` и возвращает публичный runtime API модуля.
Всё, что нужно внешнему коду в runtime, должно быть частью API, который возвращает фабрика.
Модуль без cross-domain зависимостей экспортирует фабрику без аргументов. Модуль с зависимостями — фабрику, принимающую зависимости доменными именами. Типы всегда экспортируются напрямую через `export type` — `import type` не является runtime-зависимостью.
Компоновка фабрик происходит на уровне модуля-потребителя: screen, layout, widget или любой другой модуль группы «Композиция».
### Примеры
Пример реализации фабрики в React см. в [Создание фабрики](/examples/react/factory).
Пример композиции фабрик в React screen-модуле см. в [Композиция фабрик](/examples/react/factory-composition).
Пример композиции фабрик через React Provider см. в [Композиция через Provider](/examples/react/composition-provider).
## Жизненный цикл
Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
- Нужен на одной странице → `screens/{name}/parts/`
- Появился в 2+ местах → поднимается по природе:
- абстрактный UI → `ui/`
- блок с данными/логикой → `widgets/`
- представление бизнес-домена → `business/{area}/parts/`
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.

235
projects/slm-design/canons/architecture/monorepo.md Normal file
View File

@@ -0,0 +1,235 @@
---
title: Монорепозитории
description: Правила применения SLM Design для frontend-проектов, находящихся в монорепозитории
---
# Монорепозитории
Раздел описывает, как применять SLM Design, когда фронтенд-проекты находятся в одном монорепозитории. В нём показано, что остаётся внутри приложений, что можно выносить в `packages/` и какие ограничения действуют для общих пакетов.
## Определение
**Монорепозиторий — внешний уровень организации нескольких фронтенд-приложений и общих пакетов. SLM применяется внутри каждого приложения, а frontend-пакеты, относящиеся к SLM, содержат переиспользуемый код, вынесенный из слоёв `ui`, `infra` и `shared`.**
## Базовая структура
Каждое приложение внутри `apps/` сохраняет собственную SLM-структуру в `src/`.
```text
repo/
├── apps/
│ ├── web/
│ │ └── src/
│ │ ├── app/
│ │ ├── layouts/
│ │ ├── screens/
│ │ ├── widgets/
│ │ ├── business/
│ │ ├── infra/
│ │ ├── ui/
│ │ └── shared/
│ └── admin/
│ └── src/
│ └── ...
└── packages/
├── ui/
│ ├── button/ # самостоятельный пакет UI-модуля
│ ├── input/ # самостоятельный пакет UI-модуля
│ └── modal/ # самостоятельный пакет UI-модуля
├── infra/
│ ├── theme/ # самостоятельный пакет infra-модуля
│ ├── backend-api/ # самостоятельный пакет infra-модуля
│ └── logger/ # самостоятельный пакет infra-модуля
└── shared/ # единый shared-пакет
├── package.json
└── src/
├── lib/ # переиспользуемые утилиты
├── helpers/ # переиспользуемые helpers
└── index.ts
```
`apps/{app}/src` — граница SLM-приложения. `packages/*` находятся выше SLM и не добавляют новые архитектурные слои.
## Группировка frontend-пакетов
Frontend-пакеты, вынесенные из SLM-приложений, рекомендуется группировать по источнику кода: `ui`, `infra`, `shared`.
```text
packages/ui/* # пакеты UI-модулей
packages/infra/* # пакеты infra-модулей
packages/shared # единый shared-пакет
```
Эта группировка повторяет названия SLM-слоёв для навигации, но сама не является слоистой архитектурой внутри `packages/`. Монорепозиторий может содержать другие пакеты: tooling, конфиги, SDK, схемы, e2e и другие технические пакеты вне SLM.
## Пакет и модуль
Пакет не равен SLM-модулю: модуль — архитектурная единица внутри слоя приложения, package — единица монорепозитория для переиспользования, владения, сборки и публикации.
В `packages/ui/*` размещаются пакеты самостоятельных UI-модулей. В `packages/infra/*` размещаются пакеты самостоятельных инфраструктурных модулей. `packages/shared` устроен иначе: это единый пакет для переиспользуемых утилит, helpers и другого фундаментального кода без привязки к конкретному приложению.
```text
packages/ui/button/
packages/ui/modal/
packages/infra/theme/
packages/infra/backend-api/
packages/shared/
```
## Что остаётся в приложении
Слои `app`, `layouts`, `screens`, `widgets` и `business` остаются внутри конкретного приложения.
```text
apps/web/src/app/
apps/web/src/layouts/
apps/web/src/screens/
apps/web/src/widgets/
apps/web/src/business/
```
`app`, `layouts` и `screens` привязаны к роутингу, каркасу и страницам конкретного приложения. `widgets` не выносятся в пакеты, потому что это слой композиции интерфейса приложения.
`business` не выносится в `packages/*`. Домены остаются рядом со сценариями приложения, чтобы не превращать монорепозиторий в общий бизнес-слой.
## Что можно выносить
В пакеты выносится только код из `ui`, `infra` и `shared`, который потенциально будет использоваться в двух и более фронтенд-приложениях монорепозитория.
| Группа | Что выносить | Пример |
|--------|--------------|--------|
| `packages/ui/*` | Самостоятельные UI-модули без бизнес-логики | `packages/ui/button` |
| `packages/infra/*` | Самостоятельные технические сервисы | `packages/infra/backend-api` |
| `packages/shared` | Общие утилиты, helpers и фундаментальный код | `packages/shared` |
Пакет можно создавать сразу, если модуль имеет общую природу и ожидается его переиспользование между приложениями. App-specific код остаётся внутри приложения.
## UI-пакеты
В `packages/ui/*` размещаются переиспользуемые UI-модули.
```text
packages/ui/button/
├── package.json
└── src/
├── button.tsx
├── styles/
├── types/
└── index.ts
```
UI-пакет не содержит бизнес-логику, обращения к API, сценарные хуки приложения и композицию страниц.
## Infra-пакеты
В `packages/infra/*` размещаются переиспользуемые инфраструктурные модули.
```text
packages/infra/backend-api/
├── package.json
└── src/
├── clients/
├── config/
├── types/
└── index.ts
```
Привязанные к конкретному приложению сервисы остаются в `apps/{app}/src/infra`. Например, локализация со словарями конкретного продукта остаётся в приложении; общим пакетом может быть только переиспользуемый i18n-движок.
## Shared-пакет
`packages/shared` является единым пакетом.
```text
packages/shared/
├── package.json
└── src/
├── lib/
├── helpers/
└── index.ts
```
В `packages/shared` сразу выносится общий фундаментальный код: чистые функции, helpers, утилиты, независимые константы и другой код без знания о продукте.
Проектные стили, типы приложения, продуктовые конфиги и ресурсы, завязанные на одно приложение, в общий `shared` не выносятся.
## Имена пакетов и импорты
Путь импорта задаётся `name` в `package.json`, а не расположением директории.
```json
{
"name": "@repo/theme"
}
```
```text
packages/infra/theme/package.json
```
```ts
import { ThemeProvider } from '@repo/theme'
```
Пакеты должны импортироваться только через публичный API. Deep imports внутрь пакета запрещены.
```ts
// Хорошо
import { Button } from '@repo/button'
// Плохо
import { Button } from '@repo/button/src/button'
```
## Зависимости
На уровне монорепозитория приложения зависят от пакетов, а пакеты не зависят от приложений.
```text
apps → packages
packages -/→ apps
```
Внутри приложения продолжает действовать обычное направление зависимостей SLM.
```text
app → [ layouts | screens ] → widgets → business → infra → ui → shared
```
Пакеты не должны нарушать природу своей группы: `packages/ui/*` не импортирует `packages/infra/*`, `packages/shared` не импортирует другие группы, а `packages/infra/*` не знает о приложениях.
## Когда не выносить
Не выносите код в пакет, если он не может быть использован в двух и более фронтенд-приложениях, зависит от роутинга или страниц, содержит бизнес-логику, отражает продуктовую композицию конкретного интерфейса или не имеет стабильного публичного API.
Фактическое использование в одном приложении не запрещает пакет, если модуль имеет общую природу и потенциально нужен нескольким приложениям.
```text
# Плохо
apps/web/src/screens/home/parts/promo-section/
packages/ui/promo-section/
```
Если блок нужен только одной странице или отражает продуктовую композицию конкретного приложения, он остаётся локальным `parts/`-модулем.
## Конфигурационные пакеты
Конфигурационные пакеты не относятся к SLM-архитектуре.
Если в монорепозитории есть общие настройки TypeScript, ESLint, сборки или форматирования, они относятся к tooling-инфраструктуре репозитория. Такие пакеты могут находиться в `packages/`, но их структура зависит от выбранного инструментария и не участвует в правилах слоёв внутри `src/`.
## Правила
- SLM применяется внутри каждого `apps/{app}/src`.
- Frontend-пакеты, вынесенные из SLM-приложений, группируются в `packages/ui`, `packages/infra`, `packages/shared`.
- Группы `packages/ui`, `packages/infra`, `packages/shared` не являются SLM-слоями.
- В `packages/ui/*` размещаются пакеты самостоятельных UI-модулей.
- В `packages/infra/*` размещаются пакеты самостоятельных инфраструктурных модулей.
- `packages/shared` является единым пакетом для переиспользуемых утилит и helpers.
- Модуль можно размещать в пакете, если он потенциально будет использоваться в двух и более фронтенд-приложениях.
- `business`, `app`, `layouts`, `screens`, `widgets` не выносятся в пакеты.
- Проектные стили, типы приложения и продуктовые конфиги не выносятся в `packages/shared`.
- Пакеты не импортируют приложения.
- Межпакетные импорты идут только через публичный API.
- Deep imports внутрь пакетов запрещены.
- Локальная колокация важнее преждевременного выноса в `packages/*`.

181
projects/slm-design/canons/architecture/segments.md Normal file
View File

@@ -0,0 +1,181 @@
---
title: Сегменты
description: Сегменты внутри модуля (ui/, model/, lib/ и др.), назначение и правила размещения файлов
---
# Сегменты
Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит.
## Определение
**Сегмент — папка внутри модуля, которая группирует файлы по назначению. Набор сегментов не фиксирован — модуль включает только те, которые ему нужны. Команда сама определяет какие сегменты используются в проекте — архитектура даёт рекомендацию.**
## Обзор
| Сегмент | Содержимое |
|---------|------------|
| `ui/` | Презентационные компоненты родительского модуля |
| `parts/` | Вложенные модули со своими сегментами |
| `hooks/` | React-хуки |
| `stores/` | Сторы состояния |
| `services/` | Работа с внешними источниками данных |
| `mappers/` | Трансформация данных между форматами |
| `types/` | TypeScript-типы и интерфейсы |
| `styles/` | Стили |
| `lib/` | Утилиты и хелперы модуля |
| `config/` | Константы и конфигурация |
## Сегмент ui/
Презентационные компоненты родительского модуля. `ui/` содержит только компоненты, которые отвечают за отображение части интерфейса и не выходят за границы своего модуля.
Компонент в `ui/`:
- Находится в собственной папке.
- Может содержать только `{name}.tsx`, `index.ts`, `styles/`, `types/`.
- Не содержит любые компоненты.
- Не содержит любые модули.
- Не импортирует код проекта за пределами родительского модуля.
- Не делает внешние запросы.
- Не вызывает сценарные хуки.
- Не получает данные самостоятельно, не выбирает источник данных и не композирует данные.
- Не содержит бизнес-логику или сценарную логику.
Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе [Компонент](/architecture/modules#компонент).
Корневой файл модуля в `ui/` не размещается. Он лежит в корне модуля: `{module-name}.tsx`.
```text
user/
├── ui/
│ ├── user-avatar/
│ │ ├── user-avatar.tsx
│ │ ├── styles/
│ │ │ └── user-avatar.module.css
│ │ ├── types/
│ │ │ └── user-avatar-props.type.ts
│ │ └── index.ts
│ └── user-status/
│ ├── user-status.tsx
│ └── index.ts
├── types/
├── hooks/
├── user.tsx
└── index.ts
```
Если UI-сущности нужна внутренняя декомпозиция, сценарная логика, получение данных или собственные архитектурные зависимости — это уже не компонент в `ui/`, а модуль в `parts/`.
## Сегмент parts/
Вложенные модули со своими сегментами. `parts/` содержит только модули: каждый элемент `parts/` — папка полноценного модуля с собственным публичным API. Отдельные `.tsx`, стили, хуки или произвольные файлы в `parts/` не размещаются.
```text
home/
├── parts/
│ ├── hero-section/
│ │ ├── hero-section.tsx
│ │ ├── styles/
│ │ ├── parts/
│ │ │ └── top-banner/
│ │ │ ├── top-banner.tsx
│ │ │ └── index.ts
│ │ └── index.ts
│ └── features-section/
│ ├── features-section.tsx
│ ├── hooks/
│ └── index.ts
├── home.screen.tsx
└── index.ts
```
Отличие от `ui/`: элемент `parts/` — модульная папка со своими сегментами. Элемент `ui/` — компонент родительского модуля без собственной архитектурной ответственности.
Вложенность `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
```

249
projects/slm-design/canons/examples/react/composition-provider.md Normal file
View File

@@ -0,0 +1,249 @@
---
title: Композиция через Provider
description: Пример композиции бизнес-фабрик screen-модуля через React Provider
---
# Композиция через Provider
Раздел показывает, как screen-модуль может получить готовую композицию бизнес-доменов через React Context, не вызывая фабрики внутри себя.
## Идея
Screen получает готовый API бизнес-доменов через React Context. Граф фабрик собирается снаружи, например в роутере, а внутренние `parts/` достают нужные домены через хук без пропс-дриллинга.
## Принципы
1. **Принадлежность.** Provider, Context и хук принадлежат конкретному screen-модулю и лежат в его сегментах.
2. **Внутренний тип.** Тип композиции не экспортируется наружу — это закрывает доступ из бизнес-модулей.
3. **Внутренний хук.** Хук доступа не экспортируется — доступен только внутри screen и его `parts/`.
4. **Публичный Provider.** Только Provider экспортируется через `index.ts`, чтобы роутер мог обернуть screen.
5. **Сборка снаружи.** Граф фабрик собирается в роутере или другом композиторе, screen фабрики не вызывает.
6. **Запрет для бизнеса.** Бизнес-модули не используют провайдеры композиции. Cross-domain зависимости передаются только через аргументы фабрики.
## Структура модуля
```text
screens/main/
├── main.screen.tsx
├── providers/
│ └── main-composition.provider.tsx
├── hooks/
│ └── use-main-composition.hook.ts
├── types/
│ └── main-composition.type.ts
├── parts/
│ └── featured-products/
│ ├── featured-products.tsx
│ └── index.ts
└── index.ts
```
Сегмент `providers/` — расширение стандартного набора SLM. Спецификация это разрешает: команда сама определяет, какие сегменты используются.
## Распределение по сегментам
| Файл | Сегмент | Назначение |
|------|---------|------------|
| `main-composition.type.ts` | `types/` | TypeScript-тип композиции |
| `main-composition.provider.tsx` | `providers/` | Context и Provider-компонент |
| `use-main-composition.hook.ts` | `hooks/` | React-хук доступа |
| `main.screen.tsx` | корень | Корневой компонент screen-модуля |
| `featured-products/` | `parts/` | Вложенный модуль со своим публичным API |
## Тип композиции
Файл: `screens/main/types/main-composition.type.ts`.
Тип описывает, какие бизнес-домены доступны на этой странице. Он не экспортируется через `index.ts`, чтобы другие модули не зависели от внутренней формы композиции screen.
```ts
import type { CatalogApi } from '@/business/catalog'
import type { CartApi } from '@/business/cart'
export type MainComposition = {
catalog: CatalogApi
cart: CartApi
}
```
## Context и Provider
Файл: `screens/main/providers/main-composition.provider.tsx`.
Context — внутренняя деталь Provider, наружу он не экспортируется. Значение `null` по умолчанию нужно, чтобы хук мог проверить отсутствие Provider в дереве.
Provider-компонент экспортируется через `index.ts`. Роутер передаёт в `value` уже собранный граф фабрик со стабильной ссылкой.
```tsx
import { createContext, type ReactNode } from 'react'
import type { MainComposition } from '../types/main-composition.type'
export const MainCompositionContext = createContext<MainComposition | null>(null)
type Props = {
value: MainComposition
children: ReactNode
}
export const MainCompositionProvider = ({ value, children }: Props) => (
<MainCompositionContext.Provider value={value}>
{children}
</MainCompositionContext.Provider>
)
```
## Хук доступа
Файл: `screens/main/hooks/use-main-composition.hook.ts`.
Хук остаётся внутренним и не экспортируется через `index.ts` модуля. Он доступен только внутри screen и его `parts/`.
Если хук используется вне Provider, он бросает ошибку. Это даёт раннюю диагностику неправильной композиции дерева.
```ts
import { useContext } from 'react'
import { MainCompositionContext } from '../providers/main-composition.provider'
export const useMainComposition = () => {
const ctx = useContext(MainCompositionContext)
if (!ctx) {
throw new Error('useMainComposition must be used within MainCompositionProvider')
}
return ctx
}
```
## Сборка графа в роутере
Файл: `app/router.tsx`.
Роутер или другой композитор собирает граф фабрик в точке использования screen. Каждый домен получает свои зависимости через аргументы фабрики.
Фабрики вызываются вне React-компонента, если не зависят от runtime-параметров. Так API доменов не пересоздаётся на каждый рендер route-компонента.
```tsx
import { MainScreen, MainCompositionProvider } from '@/screens/main'
import { catalogFactory } from '@/business/catalog'
import { cartFactory } from '@/business/cart'
import { authFactory } from '@/business/auth'
const auth = authFactory()
const catalog = catalogFactory()
const cart = cartFactory({ auth })
const MainRoute = () => (
<MainCompositionProvider value={{ catalog, cart }}>
<MainScreen />
</MainCompositionProvider>
)
```
## Корневой компонент screen
Файл: `screens/main/main.screen.tsx`.
Screen получает нужные домены из композиции и достаёт из API готовые хуки, компоненты или функции. В JSX используются уже локальные `useCategories` и `CategoryList`, а не обращение к фабричному API через точку.
```tsx
import { useMainComposition } from './hooks/use-main-composition.hook'
import { FeaturedProducts } from './parts/featured-products'
export const MainScreen = () => {
const { catalog } = useMainComposition()
const { useCategories, CategoryList } = catalog
const categories = useCategories()
return (
<div>
<CategoryList categories={categories} />
<FeaturedProducts />
</div>
)
}
```
## Вложенный part
Файл: `screens/main/parts/featured-products/featured-products.tsx`.
Вложенный модуль получает доступ к той же композиции родительского screen. Промежуточные компоненты не прокидывают домены через props.
Из API доменов достаются готовые сущности: `useFeatured`, `ProductCard` и `addItem`. Компонент работает с ними напрямую.
```tsx
import { useMainComposition } from '../../hooks/use-main-composition.hook'
export const FeaturedProducts = () => {
const { catalog, cart } = useMainComposition()
const { useFeatured, ProductCard } = catalog
const { addItem } = cart
const products = useFeatured()
return (
<div>
{products.map((product) => (
<ProductCard
key={product.id}
product={product}
onAdd={() => addItem(product.id)}
/>
))}
</div>
)
}
```
Файл: `screens/main/parts/featured-products/index.ts`.
```ts
export { FeaturedProducts } from './featured-products'
```
## Публичный API screen-модуля
Файл: `screens/main/index.ts`.
Наружу экспортируются только screen и его Provider. `MainComposition`, `MainCompositionContext` и `useMainComposition` остаются деталями реализации.
```ts
export { MainScreen } from './main.screen'
export { MainCompositionProvider } from './providers/main-composition.provider'
```
## Почему тип композиции не экспортируется
Внутренний тип закрывает доступ к форме композиции из внешних модулей. Бизнес-модуль не должен знать, какие домены собраны для конкретного screen.
Такой импорт из бизнес-модуля не должен быть возможен через публичный API screen.
```ts
import type { MainComposition } from '@/screens/main'
```
Когда тип остаётся внутренним, такая связь невозможна через публичный API screen-модуля.
## Почему хук не экспортируется
Если хук доступа сделать публичным, любой модуль сможет вызвать его напрямую. Внутренний хук доступен только через относительные импорты внутри screen-модуля и его `parts/`.
## Почему Provider экспортируется
Provider безопасно экспортировать: сам по себе он не даёт доступ к данным, а только принимает готовую композицию и передаёт её детям внутри React-дерева.
## Стабильность value
Фабрики создаются на уровне модуля, поэтому `catalog` и `cart` сохраняют ссылки между рендерами `MainRoute`.
Если домены зависят от runtime-параметров, граф нужно собирать в отдельном композиторе для этих параметров и передавать в Provider уже готовую композицию.
## Расширение на другие screen-модули
Паттерн повторяется для каждого screen, которому нужна композиция бизнес-доменов.
```text
screens/checkout/providers/checkout-composition.provider.tsx
screens/checkout/hooks/use-checkout-composition.hook.ts
screens/checkout/types/checkout-composition.type.ts
```
Имена включают имя screen-модуля. Не используйте универсальные названия вроде `useComposition` или `useScope`: по имени файла должно быть понятно, к какой странице привязан Context.

52
projects/slm-design/canons/examples/react/factory-composition.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: Композиция фабрик
description: Пример композиции business-фабрик на уровне screen-модуля в React-проекте
---
# Композиция фабрик
Раздел показывает, как собрать API нескольких business-модулей в React screen-модуле. Пример подходит для простой композиции, когда screen сам является точкой использования доменов.
## Идея
Композиция фабрик выполняется в модуле-потребителе: screen, layout или другом модуле группы «Композиция». Business-модули не импортируют runtime-код друг друга напрямую, а cross-domain зависимости получают только через аргументы фабрик.
## Структура screen-модуля
```text
screens/home/
├── home.screen.tsx
└── index.ts
```
## Сборка фабрик
Файл: `screens/home/home.screen.tsx`.
```tsx
import { customerFactory } from '@/business/customer'
import { orderFactory } from '@/business/order'
const customer = customerFactory()
const order = orderFactory({ customer })
const { useOrder, OrderCard } = order
export const HomeScreen = () => {
const currentOrder = useOrder()
return <OrderCard order={currentOrder} />
}
```
`customerFactory` создаётся первой, потому что `orderFactory` зависит от части API домена `customer`. Модуль `order` не импортирует `customer` в runtime — зависимость передаётся снаружи.
## Публичный API screen-модуля
Файл: `screens/home/index.ts`.
```ts
export { HomeScreen } from './home.screen'
```
Screen экспортирует только собственный публичный API. Собранные экземпляры business API остаются деталями реализации screen-модуля.

114
projects/slm-design/canons/examples/react/factory.md Normal file
View File

@@ -0,0 +1,114 @@
---
title: Создание фабрики
description: Пример создания фабрики business-модуля в React-проекте
---
# Создание фабрики
Раздел показывает, как оформить фабрику business-модуля в React-проекте: описать публичный API, зависимости и функцию, возвращающую runtime API.
## Структура business-модуля
Фабрика лежит в корне business-модуля. Типы публичного API и зависимостей размещаются в `types/`.
```text
business/customer/
├── customer.factory.ts
├── hooks/
├── types/
│ ├── customer.type.ts
│ ├── customer-api.type.ts
│ └── customer-factory.type.ts
├── ui/
└── index.ts
```
## Тип публичного API
Публичный API описывает runtime-возможности, которые модуль отдаёт потребителям: хуки, компоненты и сценарные методы.
```ts
// business/customer/types/customer-api.type.ts
import type { ReactNode } from 'react'
import type { Customer } from './customer.type'
export type CustomerCardProps = {
customer: Customer
}
export type CustomerApi = {
useCustomer: () => Customer | null
CustomerCard: (props: CustomerCardProps) => ReactNode
}
```
```ts
// business/customer/types/customer-factory.type.ts
import type { CustomerApi } from './customer-api.type'
export type CustomerFactory = () => CustomerApi
```
## Фабрика без зависимостей
Если модулю не нужны другие домены в runtime, фабрика создаётся без аргументов.
```ts
// business/customer/customer.factory.ts
import { useCustomer } from './hooks/use-customer.hook'
import { CustomerCard } from './ui/customer-card'
import type { CustomerFactory } from './types/customer-factory.type'
export const customerFactory: CustomerFactory = () => {
return {
useCustomer,
CustomerCard,
}
}
```
```ts
// business/customer/index.ts
export { customerFactory } from './customer.factory'
export type { Customer } from './types/customer.type'
export type { CustomerApi } from './types/customer-api.type'
export type { CustomerFactory } from './types/customer-factory.type'
```
## Фабрика с зависимостями
Если модулю нужен другой домен в runtime, зависимость передаётся аргументом фабрики. Тип зависимости описывает только нужную часть API.
```ts
// business/order/types/order-deps.type.ts
import type { CustomerApi } from '@/business/customer'
export type OrderDeps = {
customer: Pick<CustomerApi, 'useCustomer'>
}
```
```ts
// business/order/types/order-factory.type.ts
import type { OrderApi } from './order-api.type'
import type { OrderDeps } from './order-deps.type'
export type OrderFactory = (deps: OrderDeps) => OrderApi
```
```ts
// business/order/order.factory.ts
import { createUseOrder } from './hooks/use-order.hook'
import { OrderCard } from './ui/order-card'
import type { OrderFactory } from './types/order-factory.type'
export const orderFactory: OrderFactory = (deps) => {
const useOrder = createUseOrder(deps)
return {
useOrder,
OrderCard,
}
}
```

27
projects/slm-design/docs/.vitepress/config.ts Normal file
View File

@@ -0,0 +1,27 @@
import { defineConfig } from 'vitepress';
import taskLists from 'markdown-it-task-lists';
import llmstxt from 'vitepress-plugin-llms';
import { themeSyncHead } from '../../../_shared/docs/vitepress/themeHead';
import { sidebar, site } from '../docs.config';
export default defineConfig({
title: site.title,
description: site.description,
base: site.base,
outDir: site.outDir,
srcDir: 'content',
cleanUrls: true,
head: [...themeSyncHead],
vite: {
plugins: [llmstxt()],
},
markdown: {
config(md) {
md.use(taskLists);
},
},
themeConfig: {
sidebar,
socialLinks: [],
},
});

1
projects/slm-design/docs/.vitepress/theme/index.ts Normal file
View File

@@ -0,0 +1 @@
export { default } from '../../../../_shared/docs/vitepress/theme';

46
projects/slm-design/docs/docs.config.ts Normal file
View File

@@ -0,0 +1,46 @@
export const site = {
title: 'SLM Design',
description: 'Каноны архитектуры SLM Design',
base: '/slm-design/',
outDir: '../../../public/slm-design',
};
/**
* Карта монтирования исходных канонов в VitePress-документацию.
*
* `source` указывает на markdown-файл внутри `canons/`.
* `target` задаёт путь, по которому этот файл попадёт в `docs/content/`
* и станет страницей итоговой документации.
*/
export const mounts = [
{ target: 'index.md', source: 'canons/architecture/index.md' },
{ target: 'architecture/index.md', source: 'canons/architecture/index.md' },
{ target: 'architecture/layers.md', source: 'canons/architecture/layers.md' },
{ target: 'architecture/modules.md', source: 'canons/architecture/modules.md' },
{ target: 'architecture/segments.md', source: 'canons/architecture/segments.md' },
{ target: 'architecture/monorepo.md', source: 'canons/architecture/monorepo.md' },
{ target: 'examples/react/factory.md', source: 'canons/examples/react/factory.md' },
{ target: 'examples/react/factory-composition.md', source: 'canons/examples/react/factory-composition.md' },
{ target: 'examples/react/composition-provider.md', source: 'canons/examples/react/composition-provider.md' },
];
export const sidebar = [
{
text: 'Архитектура',
items: [
{ text: 'Обзор', link: '/architecture/' },
{ text: 'Слои', link: '/architecture/layers' },
{ text: 'Модули', link: '/architecture/modules' },
{ text: 'Сегменты', link: '/architecture/segments' },
{ text: 'Монорепозитории', link: '/architecture/monorepo' },
],
},
{
text: 'Примеры React',
items: [
{ text: 'Создание фабрики', link: '/examples/react/factory' },
{ text: 'Композиция фабрик', link: '/examples/react/factory-composition' },
{ text: 'Композиция через Provider', link: '/examples/react/composition-provider' },
],
},
];

5
projects/slm-design/project.config.ts Normal file
View File

@@ -0,0 +1,5 @@
export default {
slug: 'slm-design',
docsDir: 'docs',
archive: true,
} as const;

0
projects/slm-design/scripts/.gitkeep Normal file
View File

20
projects/template-sync-strategy/build.ts Normal file
View File

@@ -0,0 +1,20 @@
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { prepareDocs } from '../_shared/lib/prepare-docs';
import { run } from '../_shared/lib/run';
import { writeZipFromDirectory } from '../_shared/lib/zip';
import config from './project.config';
const projectDir = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(projectDir, '../..');
const docsDir = path.join(projectDir, config.docsDir);
await prepareDocs(projectDir, config);
run('npx', ['vitepress', 'build', docsDir], rootDir);
if (config.archive) {
const zipPath = path.join(rootDir, 'public', config.slug, `${config.slug}.zip`);
writeZipFromDirectory(path.join(docsDir, 'content'), zipPath, config.slug);
console.log(`Собран ${path.relative(rootDir, zipPath)}`);
}

72
projects/template-sync-strategy/canons/concepts/model.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Модель веток
description: Роли веток и remote в стратегии обновления проекта от шаблона.
---
# Модель веток
Целевая схема:
```text
templates/master -> template -> sync/* -> master
```
Это логическая модель ответственности. Она не требует физически разделять файлы шаблона и приложения по папкам.
## templates/master
`templates/master` — это `master` из репозитория шаблона.
В репозитории приложения он доступен через remote `templates`:
```bash
git remote add templates <template-repo-url>
git fetch templates
```
Этот remote считается источником обновлений шаблона.
## template
`template` — чистый слепок шаблона внутри репозитория приложения.
Его задача — показать, какая версия шаблонной базы сейчас доступна приложению.
В `template` нельзя коммитить руками изменения приложения. Эта ветка обновляется только из `templates/master`.
## master
`master` — основная ветка приложения.
Она содержит:
- базу шаблона;
- продуктовый код;
- локальные настройки приложения;
- историю применения обновлений шаблона.
`master` не используется как место ручного решения конфликтов при обновлении шаблона.
## sync/*
`sync/*` — временная ветка для обновления приложения от шаблона.
Она создаётся от актуального `origin/master`, после чего в неё вливается `origin/template`.
Пример:
```bash
git fetch origin
git switch -c sync/update-template-v2 origin/master
git merge origin/template
```
Если появляются конфликты, они решаются именно в этой ветке.
## Почему нужен отдельный sync-слой
Нельзя безопасно использовать `template` как source branch для прямого PR/MR в `master`: если возникнет конфликт, решение может попасть в `template`.
После этого `template` перестанет быть чистым слепком шаблона. Git начнёт видеть в ней не только шаблон, но и локальные решения конкретного приложения.
`sync/*` можно пачкать conflict resolve-коммитами, проверками и правками совместимости. Эта ветка временная и удаляется после merge.

47
projects/template-sync-strategy/canons/concepts/rules.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: Правила процесса
description: Набор правил, который удерживает template чистой, а обновления шаблона контролируемыми.
---
# Правила процесса
Небольшой набор правил удерживает схему чистой.
## Делаем
- `template` обновляем только из `templates/master`.
- `sync/*` создаём от `origin/master`.
- `origin/template` вливаем в `sync/*`, а не напрямую в `master`.
- Конфликты решаем только в `sync/*`.
- `sync/* -> master` вливаем через PR/MR.
- Для sync-PR/MR отключаем squash.
## Не делаем
- Не правим `template` руками.
- Не коммитим изменения приложения в `template`.
- Не мержим `template -> master` напрямую.
- Не решаем конфликты в `master`.
- Не включаем squash для `sync/* -> master`.
## Почему squash нельзя
Squash может уничтожить нормальную связь истории `master` с историей `template`.
Git использует историю, чтобы понимать, какие изменения шаблона уже были доставлены в приложение. Если результат обновления шаблона превратить в один squash-коммит, связь с исходными коммитами шаблона станет хуже или исчезнет.
Для sync-PR/MR допустимы:
```text
fast-forward merge = хорошо
merge commit = допустимо
squash merge = нельзя
```
## Почему template нельзя пачкать
`template` — эталонный слепок оригинального шаблона.
Если в неё попадает локальное решение конфликта или изменение приложения, она перестаёт отвечать на вопрос: “какая версия шаблона сейчас подключена к приложению?”.
После этого ломается главная граница ответственности: шаблон отдельно, приложение отдельно, конфликтная зона отдельно.

44
projects/template-sync-strategy/canons/concepts/why.md Normal file
View File

@@ -0,0 +1,44 @@
---
title: Зачем это нужно
description: Почему шаблону нужен процесс обновления, а не только быстрый старт нового проекта.
---
# Зачем это нужно
Шаблон закрывает повторяющуюся техническую базу проекта: CI/CD, Dockerfile, зависимости, lint, build, структуру каталогов и базовую документацию.
Это снимает рутину на старте. Команде не нужно каждый раз заново собирать одинаковый технический каркас.
## Проблема после старта
Создать проект легко. Поддерживать 10-20 проектов сложнее.
Сначала проекты похожи. Потом они начинают расходиться:
- В одном проекте обновили CI, в другом забыли.
- В одном проекте Dockerfile остался из шаблона, в другом его локально поправили.
- В одном проекте зависимости уже свежие, в другом остались старые версии.
- В одном проекте изменения шаблона перенесли руками, в другом потеряли.
Без процесса обновления шаблон перестаёт быть общей основой. Он остаётся только способом быстро создать первый коммит.
## Что ломается без стратегии
Когда шаблон нельзя нормально обновлять:
- проекты начинают жить своей жизнью;
- граница между шаблоном и приложением теряется;
- обновления превращаются в ручное копирование;
- конфликты решаются прямо в рабочих ветках;
- становится непонятно, какой проект на какой версии шаблона;
- Git-история перестаёт быть источником правды.
Это особенно больно, когда приложений много. Для одного проекта ручной перенос ещё можно пережить. Для набора проектов нужен единый маршрут обновления.
## Цель стратегии
Стратегия не пытается убрать конфликты полностью. Она делает так, чтобы конфликты возникали в предсказуемом месте, проходили review и не ломали чистую ветку шаблона.
Главная формулировка:
> Шаблон должен обновляться так же контролируемо, как обычная фича: через ветку, проверку и PR/MR.

48
projects/template-sync-strategy/canons/index.md Normal file
View File

@@ -0,0 +1,48 @@
---
title: Template Sync Strategy
description: Управляемое обновление проектов от шаблона через чистую ветку template, временные sync-ветки и PR/MR.
keywords: [template sync, шаблон проекта, обновление шаблона, git template, sync branch, template branch]
---
# Template Sync Strategy
Template Sync Strategy описывает процесс, при котором приложение создаётся от шаблона и дальше регулярно получает обновления шаблона без ручного копирования файлов.
Основной маршрут:
```text
templates/master -> template -> sync/* -> master
```
Где:
- `templates/master` — основная ветка внешнего репозитория шаблона.
- `template` — чистый слепок шаблона внутри репозитория приложения.
- `sync/*` — временная ветка, где шаблон накладывается на приложение.
- `master` — основная ветка приложения.
## Задача
Шаблон хорошо решает старт проекта: приносит CI/CD, Dockerfile, зависимости, линтер, сборку, структуру и базовую документацию. Но после старта приложения расходятся: где-то обновили CI, где-то забыли, где-то сделали локальную кастомизацию.
Стратегия нужна, чтобы шаблон оставался общей технической базой не только в первый день проекта, но и на всём жизненном цикле приложения.
## Главный принцип
Ветка `template` должна оставаться чистым слепком оригинального шаблона.
В неё нельзя коммитить изменения приложения и нельзя решать конфликты. Все конфликтные решения выполняются только во временных ветках `sync/*`.
## Состав документации
- [Зачем это нужно](./concepts/why.md) — какие проблемы появляются без update-flow.
- [Модель веток](./concepts/model.md) — роли `templates/master`, `template`, `sync/*` и `master`.
- [Правила процесса](./concepts/rules.md) — ограничения, которые удерживают схему чистой.
- [Новый проект от шаблона](./setup/clean-repository.md) — старт приложения с правильной историей.
- [Миграция существующего master](./setup/existing-master-migration.md) — одноразовое связывание несвязанных историй.
- [Обычное обновление шаблона](./workflows/update-template.md) — регулярный рабочий процесс.
- [Решение конфликтов](./workflows/resolve-conflicts.md) — где и как совместить шаблон с приложением.
- [Review и merge](./workflows/review-and-merge.md) — как доставлять sync-ветку в `master`.
- [Памятка](./reference/cheatsheet.md) — короткий набор команд.
- [Troubleshooting](./reference/troubleshooting.md) — типовые ошибки и диагностика.
- [Глоссарий](./reference/glossary.md) — основные термины.

75
projects/template-sync-strategy/canons/reference/cheatsheet.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: Памятка
description: Короткий набор команд для регулярного обновления приложения от шаблона.
---
# Памятка
Рабочая схема:
```text
templates/master -> template -> sync/* -> master
```
## Обновить template
В репозитории приложения:
```bash
git switch template
git pull --ff-only
git push
```
Это подтягивает свежий шаблон из `templates/master` и пушит его в `origin/template`.
## Создать ветку обновления
```bash
git fetch origin
git switch -c sync/update-template-vX origin/master
git merge origin/template
```
Если есть конфликты, решить их в этой же ветке:
```bash
git add .
git commit
```
## Запушить sync-ветку
```bash
git push -u origin sync/update-template-vX
```
## Влить через UI
Создать PR/MR:
```text
source: sync/update-template-vX
target: master
```
Важно:
```text
squash = off
```
## Проверка
```bash
git --no-pager log --oneline --graph --decorate --all --max-count=30
```
## Суть процесса
1. Обновить `template` из `templates/master`.
2. Создать `sync/*` от `origin/master`.
3. Влить `origin/template` в `sync/*`.
4. Решить конфликты, если есть.
5. Запушить `sync/*`.
6. Через UI влить `sync/* -> master`.

52
projects/template-sync-strategy/canons/reference/glossary.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: Глоссарий
description: Термины, которые используются в Template Sync Strategy.
---
# Глоссарий
## Template repo
Репозиторий шаблона. В нём живёт общая техническая база: CI/CD, Dockerfile, зависимости, линтер, сборка, структура и документация.
## App repo
Репозиторий приложения. В нём живёт продуктовый код и локальные настройки конкретного приложения.
## templates
Git remote внутри репозитория приложения, который указывает на репозиторий шаблона.
Пример:
```bash
git remote add templates <template-repo-url>
```
## templates/master
Ветка `master` из репозитория шаблона, доступная в приложении через remote `templates`.
## template
Ветка внутри репозитория приложения, которая должна быть чистым слепком `templates/master`.
## master
Основная ветка приложения. Содержит шаблонную базу плюс продуктовый слой.
## sync/*
Временные ветки для обновления приложения от шаблона. Создаются от `origin/master`, получают merge из `origin/template`, проходят review и затем вливаются в `master`.
## Fast-forward
Обновление ветки без merge-коммита, когда текущая ветка может быть просто передвинута вперёд по истории.
## Merge commit
Коммит слияния, который сохраняет связь двух историй. Допустим для `sync/* -> master`.
## Squash
Способ merge, при котором все изменения source branch превращаются в один новый коммит. Для sync-PR/MR запрещён, потому что может разрушить полезную связь истории `master` с историей `template`.

102
projects/template-sync-strategy/canons/reference/troubleshooting.md Normal file
View File

@@ -0,0 +1,102 @@
---
title: Troubleshooting
description: Типовые ошибки при обновлении проекта от шаблона и способы диагностики.
---
# Troubleshooting
## fatal: отказ слияния несвязанных историй изменений
Ошибка:
```text
fatal: отказ слияния несвязанных историй изменений
```
Причина: `master` приложения не был создан от `template`, поэтому у веток нет общего предка.
Решение: выполнить одноразовую миграцию через `sync/bootstrap-template` по инструкции [Миграция существующего master](../setup/existing-master-migration.md).
Коротко:
```bash
git switch -c sync/bootstrap-template origin/master
git merge --allow-unrelated-histories origin/template
git push -u origin sync/bootstrap-template
```
## --ff-only падает на template
Ошибка возникает при команде:
```bash
git merge --ff-only templates/master
```
Причина: в `template` появились коммиты, которых нет в шаблоне. Значит ветка перестала быть чистым слепком.
Что проверить:
```bash
git fetch templates
git --no-pager log --oneline --graph --decorate templates/master..template
```
Решение зависит от причины. Не продолжайте обновление, пока не станет понятно, какие локальные коммиты попали в `template`.
## Пустой diff в sync-ветке
Симптом:
```bash
git --no-pager diff --stat origin/master...HEAD
```
не показывает изменений.
Возможные причины:
- в шаблоне нет новых изменений;
- `origin/template` не был обновлён;
- `origin/template` не был влит в `sync/*`;
- sync-ветка создана не от актуального `origin/master`.
Что проверить:
```bash
git fetch origin
git fetch templates
git --no-pager log --oneline -1 origin/template
git --no-pager log --oneline -1 templates/master
git --no-pager log --oneline --graph --decorate --all --max-count=50
```
## Случайно включили squash
Если sync-PR/MR уже влит squash-merge, история шаблона могла не сохраниться как нормальная merge-связь.
Что сделать:
- зафиксировать факт в описании проекта;
- проверить, видит ли Git последующие обновления шаблона без повторного применения старых изменений;
- при следующем обновлении внимательно смотреть diff и конфликты;
- для будущих sync-PR/MR отключить squash.
Если ситуация стала неуправляемой, может потребоваться отдельная техническая миграция истории.
## cannot run less
Ошибка:
```text
cannot run less
```
Причина: Git пытается открыть pager `less`, которого нет в системе.
Решение: использовать `git --no-pager`:
```bash
git --no-pager log --oneline --graph --decorate --all --max-count=50
git --no-pager diff template...master
```

119
projects/template-sync-strategy/canons/setup/clean-repository.md Normal file
View File

@@ -0,0 +1,119 @@
---
title: Новый проект от шаблона
description: Старт нового приложения от шаблонного репозитория с правильной историей веток.
---
# Новый проект от шаблона
Этот сценарий подходит, когда репозиторий приложения ещё пустой или его можно безопасно пересоздать от шаблона.
Целевая модель:
```text
templates/master -> template -> sync/* -> master
```
## Условия
Есть два репозитория:
```text
template repo = репозиторий шаблона
app repo = репозиторий приложения
```
В обоих репозиториях основная ветка называется `master`.
## Подготовить шаблон
В репозитории шаблона:
```bash
cd /path/to/template-repo
git switch master
```
Если это пустой репозиторий, добавьте первый файл и запушьте `master`:
```bash
printf "# Template Repository\n\nBase template version: v1\n" > README.md
git add README.md
git commit -m "docs: добавить базовый шаблон"
git push -u origin master
```
## Подключить шаблон в приложении
В репозитории приложения:
```bash
cd /path/to/app-repo
git remote add templates <template-repo-url>
git fetch templates
```
Создайте ветку `template` от шаблона:
```bash
git switch -c template templates/master
git push -u origin template
```
Создайте ветку приложения `master` от `template`:
```bash
git switch -c master template
```
Добавьте слой приложения:
```bash
mkdir -p app
printf "Application code v1\n" > app/app.txt
git add app/app.txt
git commit -m "feat: добавить слой приложения"
git push -u origin master
```
После этого история выглядит так:
```text
template: T1
master: T1---A1
```
Где `T1` — коммит шаблона, а `A1` — коммит приложения.
## Настроить pull и push для template
Можно сделать так, чтобы на ветке `template`:
```text
git pull тянул из templates/master
git push пушил в origin/template
```
Команды:
```bash
git config branch.template.remote templates
git config branch.template.merge refs/heads/master
git config branch.template.pushRemote origin
```
Дополнительно можно запретить случайный push в репозиторий шаблона:
```bash
git remote set-url --push templates DISABLED
```
## Дальше
После первичной настройки постоянные ветки такие:
```text
template = чистый шаблон
master = приложение
```
Обновления шаблона выполняются через временные ветки `sync/*` по инструкции [Обычное обновление шаблона](../workflows/update-template.md).

144
projects/template-sync-strategy/canons/setup/existing-master-migration.md Normal file
View File

@@ -0,0 +1,144 @@
---
title: Миграция существующего master
description: Как одноразово связать master приложения с историей шаблона, если проект был создан отдельно.
---
# Миграция существующего master
Этот сценарий нужен, если в репозитории приложения уже есть `master`, но он был создан не от шаблона.
## Проблема
Если `master` приложения и `template` имеют разные корневые коммиты, Git видит две несвязанные истории.
Плохое состояние:
```text
template: T1---T2---T3
master: A1---A2
```
При попытке выполнить обычный merge Git может ответить:
```text
fatal: отказ слияния несвязанных историй изменений
```
Это означает, что у веток нет общего предка.
## Цель миграции
Нужно один раз связать истории, чтобы дальше обновления шаблона шли обычным merge-процессом.
После миграции история будет выглядеть примерно так:
```text
template: T1---T2---T3
\
master: A1---A2-----M
```
Где `M` — одноразовый merge-коммит, который связал историю приложения с историей шаблона.
## Подключить репозиторий шаблона
В репозитории приложения:
```bash
cd /path/to/app-repo
git remote add templates <template-repo-url>
git fetch templates
git fetch origin
```
Если remote `templates` уже существует:
```bash
git fetch templates
git fetch origin
```
## Создать или обновить template
Если ветки `template` ещё нет:
```bash
git switch -c template templates/master
git push -u origin template
```
Если ветка `template` уже есть:
```bash
git switch template
git merge --ff-only templates/master
git push origin template
```
Опционально настройте удобное поведение `pull` и `push`:
```bash
git config branch.template.remote templates
git config branch.template.merge refs/heads/master
git config branch.template.pushRemote origin
git remote set-url --push templates DISABLED
```
## Связать master с template
Создайте временную ветку от текущего приложения:
```bash
git fetch origin
git switch -c sync/bootstrap-template origin/master
```
Слейте шаблон с разрешением несвязанных историй:
```bash
git merge --allow-unrelated-histories origin/template
```
Если есть конфликты, решите их в ветке `sync/bootstrap-template`:
```bash
git add .
git commit
```
Если конфликтов не было, Git сам создаст merge-коммит.
Запушьте ветку:
```bash
git push -u origin sync/bootstrap-template
```
Дальше через UI или локально смержите:
```text
sync/bootstrap-template -> master
```
## Что проверить перед merge
Посмотрите граф истории:
```bash
git --no-pager log --oneline --graph --decorate --all --max-count=50
```
Убедитесь, что `sync/bootstrap-template` содержит и историю приложения, и историю шаблона.
Посмотрите итоговый diff:
```bash
git --no-pager diff origin/master...sync/bootstrap-template
```
## Когда миграцию делать не стоит
Не стоит связывать истории, если приложение только что создано и его можно безопасно пересоздать от шаблона.
Для нового проекта лучше сделать чистый старт по инструкции [Новый проект от шаблона](./clean-repository.md).

78
projects/template-sync-strategy/canons/workflows/resolve-conflicts.md Normal file
View File

@@ -0,0 +1,78 @@
---
title: Решение конфликтов
description: Почему конфликты при обновлении шаблона должны решаться только в sync-ветках.
---
# Решение конфликтов
Конфликт при обновлении шаблона — нормальная ситуация. Важно не то, что конфликт возник, а где он возник.
Правильное место для конфликтов — временная ветка `sync/*`.
## Пример
Шаблон поменял строку в `README.md`:
```text
Base template version: template-conflict-v10
```
Приложение поменяло ту же строку иначе:
```text
Base template version: application-conflict-v10
```
При merge `origin/template` в `sync/update-template-v10` появится конфликт:
```text
<<<<<<< HEAD
Base template version: application-conflict-v10
=======
Base template version: template-conflict-v10
>>>>>>> origin/template
```
Это правильное место конфликта: `master` ещё не изменён, `template` остаётся чистой, а итоговое решение можно проверить в PR/MR.
## Как решать
1. Оставайтесь в ветке `sync/*`.
2. Разберите конфликт по смыслу: что должно остаться в приложении после обновления шаблона.
3. Удалите conflict markers.
4. Проверьте проект локально.
5. Закоммитьте результат.
```bash
git status
git add .
git commit
```
## Что нельзя делать
Нельзя переносить conflict resolve в `template`.
`template` должна совпадать с шаблоном. Если решение конфликта попадёт туда, она перестанет быть эталоном и дальнейшие обновления станут менее предсказуемыми.
Нельзя решать конфликт прямо в `master`, потому что основная ветка приложения должна получать только проверенный результат через PR/MR.
## Что проверить после resolve
Посмотрите статус:
```bash
git status
```
Посмотрите diff относительно текущего приложения:
```bash
git --no-pager diff origin/master...HEAD
```
Посмотрите граф:
```bash
git --no-pager log --oneline --graph --decorate --all --max-count=50
```

75
projects/template-sync-strategy/canons/workflows/review-and-merge.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: Review и merge
description: Как проверять и вливать sync-ветку с обновлением шаблона в master приложения.
---
# Review и merge
После подготовки `sync/*` ветки обновление шаблона должно попасть в `master` через PR/MR.
## Создать PR/MR
Параметры:
```text
source: sync/update-template-vX
target: master
```
Цель review — увидеть:
- какие изменения пришли из шаблона;
- какие конфликтные решения были сделаны в `sync/*`;
- не попали ли в обновление лишние изменения приложения;
- проходят ли проверки проекта.
## Настройки merge
Для sync-PR/MR важно:
```text
squash = off
fast-forward merge = хорошо
merge commit = допустимо
squash merge = нельзя
```
Squash нельзя использовать, потому что он может уничтожить связь истории `master` с историей `template`. Особенно это критично после миграционного `sync/bootstrap-template`.
## Проверки перед merge
Проверьте граф истории:
```bash
git --no-pager log --oneline --graph --decorate --all --max-count=50
```
Проверьте итоговый diff:
```bash
git --no-pager diff origin/master...sync/update-template-vX
```
Проверьте проект обычными командами конкретного приложения, например:
```bash
npm run lint
npm run build
```
## После merge
После успешного merge в `master` можно удалить временную ветку:
```bash
git branch -d sync/update-template-vX
git push origin --delete sync/update-template-vX
```
Проверьте, что `master` теперь содержит обновление шаблона:
```bash
git fetch origin
git --no-pager log origin/template..origin/master --oneline
git --no-pager diff origin/template...origin/master
```

111
projects/template-sync-strategy/canons/workflows/update-template.md Normal file
View File

@@ -0,0 +1,111 @@
---
title: Обычное обновление шаблона
description: Повторяемый процесс доставки изменений шаблона в приложение после первичной настройки.
---
# Обычное обновление шаблона
Эта инструкция подходит после любого стартового сценария:
- [Новый проект от шаблона](../setup/clean-repository.md).
- [Миграция существующего master](../setup/existing-master-migration.md).
Целевой маршрут:
```text
templates/master -> template -> sync/* -> master
```
## 1. Обновить слепок шаблона
В репозитории приложения:
```bash
cd /path/to/app-repo
git switch template
git pull --ff-only
git push
```
Этот вариант работает, если для ветки `template` настроено:
```text
pull из templates/master
push в origin/template
```
Явная форма без зависимости от tracking-настроек:
```bash
git fetch templates
git switch template
git merge --ff-only templates/master
git push origin template
```
Если `--ff-only` падает, значит `template` перестал быть чистым слепком шаблона. Остановитесь и разберите причину до продолжения.
Проверьте, что `origin/template` обновился до шаблона:
```bash
git fetch origin
git fetch templates
git --no-pager log --oneline -1 origin/template
git --no-pager log --oneline -1 templates/master
```
Оба коммита должны совпадать.
## 2. Создать ветку обновления приложения
После обновления `template` создайте временную ветку от текущего приложения:
```bash
git fetch origin
git switch -c sync/update-template-v2 origin/master
git merge origin/template
```
Имя ветки можно менять под версию или дату:
```text
sync/update-template-v2
sync/update-template-2026-05-09
sync/update-template-1.8.0
```
Проверьте, что временная ветка реально отличается от `origin/master` изменениями шаблона:
```bash
git --no-pager diff --stat origin/master...HEAD
```
Если diff пустой, значит обновлённый `origin/template` не был влит в `sync/*` ветку или в шаблоне нет новых изменений.
## 3. Решить конфликты
Если есть конфликты, решайте их именно в `sync/*`.
После решения конфликтов:
```bash
git add .
git commit
```
Если конфликтов не было, Git сам создаст merge-коммит или выполнит fast-forward, в зависимости от истории.
## 4. Запушить sync-ветку
```bash
git push -u origin sync/update-template-v2
```
Дальше откройте PR/MR:
```text
source: sync/update-template-v2
target: master
```
Правила merge описаны в [Review и merge](./review-and-merge.md).

27
projects/template-sync-strategy/docs/.vitepress/config.ts Normal file
View File

@@ -0,0 +1,27 @@
import { defineConfig } from 'vitepress';
import taskLists from 'markdown-it-task-lists';
import llmstxt from 'vitepress-plugin-llms';
import { themeSyncHead } from '../../../_shared/docs/vitepress/themeHead';
import { sidebar, site } from '../docs.config';
export default defineConfig({
title: site.title,
description: site.description,
base: site.base,
outDir: site.outDir,
srcDir: 'content',
cleanUrls: true,
head: [...themeSyncHead],
vite: {
plugins: [llmstxt()],
},
markdown: {
config(md) {
md.use(taskLists);
},
},
themeConfig: {
sidebar,
socialLinks: [],
},
});

1
projects/template-sync-strategy/docs/.vitepress/theme/index.ts Normal file
View File

@@ -0,0 +1 @@
export { default } from '../../../../_shared/docs/vitepress/theme';

64
projects/template-sync-strategy/docs/docs.config.ts Normal file
View File

@@ -0,0 +1,64 @@
export const site = {
title: 'Template Sync Strategy',
description: 'Управляемое обновление проектов от шаблона',
base: '/template-sync-strategy/',
outDir: '../../../public/template-sync-strategy',
};
/**
* Карта монтирования исходных канонов в VitePress-документацию.
*
* `source` указывает на markdown-файл внутри `canons/`.
* `target` задаёт путь, по которому этот файл попадёт в `docs/content/`
* и станет страницей итоговой документации.
*/
export const mounts = [
{ target: 'index.md', source: 'canons/index.md' },
{ target: 'overview.md', source: 'canons/index.md' },
{ target: 'concepts/why.md', source: 'canons/concepts/why.md' },
{ target: 'concepts/model.md', source: 'canons/concepts/model.md' },
{ target: 'concepts/rules.md', source: 'canons/concepts/rules.md' },
{ target: 'setup/clean-repository.md', source: 'canons/setup/clean-repository.md' },
{ target: 'setup/existing-master-migration.md', source: 'canons/setup/existing-master-migration.md' },
{ target: 'workflows/update-template.md', source: 'canons/workflows/update-template.md' },
{ target: 'workflows/resolve-conflicts.md', source: 'canons/workflows/resolve-conflicts.md' },
{ target: 'workflows/review-and-merge.md', source: 'canons/workflows/review-and-merge.md' },
{ target: 'reference/cheatsheet.md', source: 'canons/reference/cheatsheet.md' },
{ target: 'reference/troubleshooting.md', source: 'canons/reference/troubleshooting.md' },
{ target: 'reference/glossary.md', source: 'canons/reference/glossary.md' },
];
export const sidebar = [
{
text: 'Введение',
items: [
{ text: 'Обзор', link: '/overview' },
{ text: 'Зачем это нужно', link: '/concepts/why' },
{ text: 'Модель веток', link: '/concepts/model' },
{ text: 'Правила процесса', link: '/concepts/rules' },
],
},
{
text: 'Настройка',
items: [
{ text: 'Новый проект от шаблона', link: '/setup/clean-repository' },
{ text: 'Миграция существующего master', link: '/setup/existing-master-migration' },
],
},
{
text: 'Рабочие процессы',
items: [
{ text: 'Обычное обновление шаблона', link: '/workflows/update-template' },
{ text: 'Решение конфликтов', link: '/workflows/resolve-conflicts' },
{ text: 'Review и merge', link: '/workflows/review-and-merge' },
],
},
{
text: 'Справочник',
items: [
{ text: 'Памятка', link: '/reference/cheatsheet' },
{ text: 'Troubleshooting', link: '/reference/troubleshooting' },
{ text: 'Глоссарий', link: '/reference/glossary' },
],
},
];

5
projects/template-sync-strategy/project.config.ts Normal file
View File

@@ -0,0 +1,5 @@
export default {
slug: 'template-sync-strategy',
docsDir: 'docs',
archive: true,
} as const;

Some files were not shown because too many files have changed in this diff Show More