mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
chore: удалить устаревшее содержимое preview
- удалены legacy AI-инструкции preview-приложения - удалены неиспользуемые шаблоны генерации модулей
This commit is contained in:
@@ -1 +0,0 @@
|
|||||||
export { {{name.pascalCase}}Business } from './{{name.kebabCase}}.business'
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
.root {
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры бизнес-модуля {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}BusinessParams = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}BusinessProps = RootAttrs & {{name.pascalCase}}BusinessParams
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}BusinessProps } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* <Назначение бизнес-модуля {{name.pascalCase}} в 1 строке>.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - <сценарий 1>
|
|
||||||
* - <сценарий 2>
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}}Business = (props: {{name.pascalCase}}BusinessProps) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
export { {{name.pascalCase}}Infra } from './{{name.kebabCase}}.infra'
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
.root {
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры инфраструктурного модуля {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}InfraParams = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}InfraProps = RootAttrs & {{name.pascalCase}}InfraParams
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}InfraProps } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* <Назначение инфраструктурного модуля {{name.pascalCase}} в 1 строке>.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - <сценарий 1>
|
|
||||||
* - <сценарий 2>
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}}Infra = (props: {{name.pascalCase}}InfraProps) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
export { {{name.pascalCase}}Layout } from './{{name.kebabCase}}.layout'
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
.root {
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры {{name.pascalCase}}Layout.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}LayoutParams = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}LayoutProps = RootAttrs & {{name.pascalCase}}LayoutParams
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}LayoutProps } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* <Назначение layout {{name.pascalCase}} в 1 строке>.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - <сценарий 1>
|
|
||||||
* - <сценарий 2>
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}}Layout = (props: {{name.pascalCase}}LayoutProps) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
export { {{name.pascalCase}} } from './{{name.kebabCase}}'
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
.root {
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}Params = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}Props = RootAttrs & {{name.pascalCase}}Params
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* <Назначение компонента {{name.pascalCase}} в 1 строке>.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - <сценарий 1>
|
|
||||||
* - <сценарий 2>
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}} = (props: {{name.pascalCase}}Props) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
export { {{name.pascalCase}}Screen } from './{{name.kebabCase}}.screen'
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
.root {
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры экрана {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}ScreenParams = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}ScreenProps = RootAttrs & {{name.pascalCase}}ScreenParams
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}ScreenProps } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* <Назначение экрана {{name.pascalCase}} в 1 строке>.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - <сценарий 1>
|
|
||||||
* - <сценарий 2>
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}}Screen = (props: {{name.pascalCase}}ScreenProps) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
export { use{{name.pascalCase}}Store } from './{{name.kebabCase}}.store'
|
|
||||||
export type { {{name.pascalCase}}State } from './{{name.kebabCase}}.type'
|
|
||||||
@@ -1,9 +0,0 @@
|
|||||||
import { create } from 'zustand'
|
|
||||||
import type { {{name.pascalCase}}State } from './{{name.kebabCase}}.type'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Стор {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export const use{{name.pascalCase}}Store = create<{{name.pascalCase}}State>()(() => ({
|
|
||||||
|
|
||||||
}))
|
|
||||||
@@ -1,6 +0,0 @@
|
|||||||
/**
|
|
||||||
* Состояние {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export interface {{name.pascalCase}}State {
|
|
||||||
|
|
||||||
}
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
export { {{name.pascalCase}} } from './{{name.kebabCase}}.ui'
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
.root {
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}Params = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}Props = RootAttrs & {{name.pascalCase}}Params
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* <Назначение компонента {{name.pascalCase}} в 1 строке>.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - <сценарий 1>
|
|
||||||
* - <сценарий 2>
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}} = (props: {{name.pascalCase}}Props) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
export { {{name.pascalCase}}Widget } from './{{name.kebabCase}}.widget'
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
.root {
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры виджета {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}WidgetParams = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}WidgetProps = RootAttrs & {{name.pascalCase}}WidgetParams
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}WidgetProps } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* <Назначение виджета {{name.pascalCase}} в 1 строке>.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - <сценарий 1>
|
|
||||||
* - <сценарий 2>
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}}Widget = (props: {{name.pascalCase}}WidgetProps) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
@@ -1,43 +0,0 @@
|
|||||||
# AGENTS.md
|
|
||||||
|
|
||||||
Это корневой диспетчер. Он определяет твою роль и отправляет тебя к твоему файлу инструкций. Дальше ты работаешь **строго** по нему.
|
|
||||||
|
|
||||||
## Жёсткие правила
|
|
||||||
|
|
||||||
1. Прочитай **только** файл своей роли из таблицы ниже.
|
|
||||||
2. Не читай файлы других ролей. Не читай `ai/` рекурсивно «для контекста».
|
|
||||||
3. Внутри файла роли есть свои обязательные разделы, прикладные разделы и триггеры — следуй его внутреннему протоколу, не додумывай свой.
|
|
||||||
4. Дополнительные файлы из `ai/` читай **только** когда на них явно ссылается твой файл роли или сработавший триггер.
|
|
||||||
|
|
||||||
## Определение роли
|
|
||||||
|
|
||||||
Роль определяется в таком порядке:
|
|
||||||
|
|
||||||
1. Переменная окружения `AI_ROLE`.
|
|
||||||
2. Явное указание в первом сообщении пользователя («работай как developer», «ты reviewer» и т.п.).
|
|
||||||
3. Если ни того, ни другого нет — **остановись и спроси**. Не выбирай роль сам.
|
|
||||||
|
|
||||||
## Карта ролей
|
|
||||||
|
|
||||||
| Роль | Файл инструкций | Назначение |
|
|
||||||
|--------------|-------------------|-----------------------------------------------|
|
|
||||||
| `developer` | `ai/DEVELOP.md` | Написание и редактирование кода проекта |
|
|
||||||
| `reviewer` | `ai/REVIEW.md` | Код-ревью, проверка на соответствие стайлгайду |
|
|
||||||
| `architect` | `ai/ARCHITECT.md` | Проектирование модулей, слоёв, API |
|
|
||||||
| ... | ... | ... |
|
|
||||||
|
|
||||||
> Оставь в таблице только те роли, которые реально существуют в `ai/`.
|
|
||||||
|
|
||||||
## Протокол запуска
|
|
||||||
|
|
||||||
1. Определи роль (см. выше).
|
|
||||||
2. Открой соответствующий файл из таблицы — это твой единственный источник истины.
|
|
||||||
3. Выполняй его внутренний протокол: сначала обязательные правила, затем прикладные разделы и триггеры по мере появления задач.
|
|
||||||
4. Если в ходе работы нужна инструкция, которой нет ни в твоём файле роли, ни в её триггерах — **не ищи её сам в других ролях**. Сообщи пользователю и спроси, как быть (переключить роль, дополнить инструкцию, и т.п.).
|
|
||||||
|
|
||||||
## Что запрещено
|
|
||||||
|
|
||||||
- Читать файлы других ролей даже выборочно.
|
|
||||||
- Сканировать `ai/` целиком или строить по ней собственную карту.
|
|
||||||
- Смешивать правила из разных ролей в одном ответе.
|
|
||||||
- Додумывать правила, которых нет в твоём файле роли.
|
|
||||||
@@ -1,96 +0,0 @@
|
|||||||
# Стайлгайд — Разработка
|
|
||||||
|
|
||||||
Правила и стандарты разработки на Next.js и TypeScript.
|
|
||||||
|
|
||||||
## Как работать
|
|
||||||
|
|
||||||
1. **Изучи обязательные правила** (таблица ниже) — они действуют при любой задаче.
|
|
||||||
2. Найди задачу в таблицах триггеров → открой триггер.
|
|
||||||
3. Триггер укажет какие прикладные разделы прочитать и какие шаги выполнить.
|
|
||||||
4. Перед каждой подзадачей возвращайся к триггерам — проверяй, нет ли готового.
|
|
||||||
5. Если триггера нет — ищи прикладной раздел по области задачи.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Обязательные правила
|
|
||||||
|
|
||||||
Прочитай эти разделы **до начала работы**. Соблюдай при написании любого кода.
|
|
||||||
|
|
||||||
| Раздел | Файл | Что внутри |
|
|
||||||
|--------|------|------------|
|
|
||||||
| Структура проекта | applied/project-structure.md | Организация папок и файлов |
|
|
||||||
| Архитектура | basics/architecture.md | SLM Design: слои, модули, сегменты |
|
|
||||||
| Стиль кода | basics/code-style.md | Форматирование, импорты, отступы |
|
|
||||||
| Именование | basics/naming.md | Имена файлов, переменных, событий |
|
|
||||||
| Типизация | basics/typing.md | type vs interface, generic, any/unknown |
|
|
||||||
| Документирование | basics/documentation.md | JSDoc для функций, компонентов, типов |
|
|
||||||
| Технологии | basics/tech-stack.md | Допустимые библиотеки и зависимости |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Прикладные разделы
|
|
||||||
|
|
||||||
Справочник по областям. Читай тот раздел, который относится к текущей задаче.
|
|
||||||
|
|
||||||
| Область | Файл | Когда читать |
|
|
||||||
|---------|------|--------------|
|
|
||||||
| Компоненты | applied/components.md | Создание или редактирование React-компонентов |
|
|
||||||
| Стили | applied/styles.md | CSS Modules, PostCSS, переменные, медиа-запросы |
|
|
||||||
| Файлы роутинга | applied/page-level.md | page.tsx, layout.tsx, error.tsx, not-found.tsx |
|
|
||||||
| Шаблоны и генерация | applied/templates-generation.md | Генерация кода из шаблонов |
|
|
||||||
| Настройка VS Code | applied/vscode.md | Расширения, settings.json, сниппеты |
|
|
||||||
| SVG-спрайты | applied/svg-sprites.md | Работа с SVG-иконками и спрайтами |
|
|
||||||
| Хуки | applied/hooks.md | Создание и использование кастомных хуков *(в разработке)* |
|
|
||||||
| Сторы | applied/stores.md | Глобальное состояние, Zustand *(в разработке)* |
|
|
||||||
| API | applied/api.md | Запросы, клиенты, обработка ответов *(в разработке)* |
|
|
||||||
| Локализация | applied/localization.md | i18next, переводы *(в разработке)* |
|
|
||||||
| Изображения | applied/images-sprites.md | Подключение и оптимизация изображений *(в разработке)* |
|
|
||||||
| Шрифты | applied/fonts.md | Подключение и настройка шрифтов *(в разработке)* |
|
|
||||||
| Видео | applied/video.md | Встраивание видео *(в разработке)* |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Триггеры
|
|
||||||
|
|
||||||
Пошаговые инструкции. Найди задачу → открой триггер → выполняй по шагам.
|
|
||||||
|
|
||||||
### Создание
|
|
||||||
|
|
||||||
| Задача | Триггер | Описание |
|
|
||||||
|--------|---------|----------|
|
|
||||||
| Создать компонент | triggers/develop/create-component.md | Переиспользуемый UI-элемент без бизнес-логики |
|
|
||||||
| Создать фичу | triggers/develop/create-feature.md | Самодостаточный блок с бизнес-логикой и UI |
|
|
||||||
| Создать виджет | triggers/develop/create-widget.md | Композиция нескольких фичей и сущностей |
|
|
||||||
| Создать сущность | triggers/develop/create-entity.md | Бизнес-объект с моделью данных и UI-представлением |
|
|
||||||
| Создать хук | triggers/develop/create-hook.md | Кастомный React-хук с переиспользуемой логикой |
|
|
||||||
| Создать стор | triggers/develop/create-store.md | Глобальное или модульное состояние через Zustand |
|
|
||||||
| Создать страницу | triggers/develop/create-page.md | Новый route в Next.js — экран + page.tsx |
|
|
||||||
| Создать layout | triggers/develop/create-layout.md | Общая обёртка layout.tsx для группы страниц |
|
|
||||||
| Создать проект | triggers/develop/create-project.md | Инициализация нового проекта из шаблона |
|
|
||||||
| Сгенерировать модуль | triggers/develop/generate-module.md | Создание модуля из шаблонов `.templates/` |
|
|
||||||
|
|
||||||
### Стилизация и ресурсы
|
|
||||||
|
|
||||||
| Задача | Триггер | Описание |
|
|
||||||
|--------|---------|----------|
|
|
||||||
| Стилизовать компонент | triggers/develop/style-component.md | Выбор подхода и написание CSS для компонента |
|
|
||||||
| Добавить иконку | triggers/develop/add-icon.md | SVG-иконка через спрайт-систему |
|
|
||||||
| Добавить изображение | triggers/develop/add-image.md | Растровое изображение (png, jpg, webp) |
|
|
||||||
| Добавить видео | triggers/develop/add-video.md | Встраивание видео на страницу |
|
|
||||||
| Подключить шрифт | triggers/develop/add-font.md | Подключение нового шрифта в проект |
|
|
||||||
|
|
||||||
### Данные и состояние
|
|
||||||
|
|
||||||
| Задача | Триггер | Описание |
|
|
||||||
|--------|---------|----------|
|
|
||||||
| Добавить API-запрос | triggers/develop/add-api-request.md | Клиентский запрос данных через SWR |
|
|
||||||
| Подключить стор | triggers/develop/connect-store.md | Подключение существующего стора к компоненту |
|
|
||||||
| Серверные данные (RSC) | triggers/develop/add-server-data.md | Получение данных в серверных компонентах |
|
|
||||||
|
|
||||||
### Инфраструктура
|
|
||||||
|
|
||||||
| Задача | Триггер | Описание |
|
|
||||||
|--------|---------|----------|
|
|
||||||
| Добавить перевод | triggers/develop/add-localization.md | Ключи перевода и подключение i18next |
|
|
||||||
| Добавить зависимость | triggers/develop/add-dependency.md | Подключение новой npm-библиотеки |
|
|
||||||
| Настроить VS Code | triggers/develop/setup-vscode.md | Расширения, настройки редактора, сниппеты |
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
scope: applied
|
|
||||||
keywords: [api, запрос, fetch, SWR, эндпоинт, REST, клиент]
|
|
||||||
when: "Работа с API: запросы, клиенты, обработка ответов"
|
|
||||||
---
|
|
||||||
@@ -1,118 +0,0 @@
|
|||||||
---
|
|
||||||
title: Компоненты
|
|
||||||
scope: applied
|
|
||||||
keywords: [компонент, props, jsx, ui, clsx, cl, React, FC]
|
|
||||||
when: "Создание или редактирование React-компонентов: структура, пропсы, стили"
|
|
||||||
---
|
|
||||||
# Компоненты
|
|
||||||
|
|
||||||
Правила написания React-компонентов: файловая структура модуля, типизация пропсов, документирование и реализация. Раздел охватывает компоненты всех слоёв — от `shared/ui` до `screens`.
|
|
||||||
|
|
||||||
Архитектурные слои и их назначение описаны в разделе [Архитектура](/basics/architecture).
|
|
||||||
|
|
||||||
|
|
||||||
## Правила организации
|
|
||||||
|
|
||||||
1. Один компонент — один файл.
|
|
||||||
2. Компонент не содержит бизнес-логики — логика и сайд-эффекты выносятся в хуки или сторы.
|
|
||||||
3. Дочерние компоненты размещаются в сегменте `ui/` и подчиняются тем же правилам структуры.
|
|
||||||
4. Публичный API модуля — только `index.ts`. Прямые импорты внутренних файлов запрещены.
|
|
||||||
|
|
||||||
## Базовая структура компонента
|
|
||||||
|
|
||||||
Минимальный набор файлов: компонент, стили, типы и публичный экспорт.
|
|
||||||
|
|
||||||
```text
|
|
||||||
container/
|
|
||||||
├── styles/
|
|
||||||
│ └── container.module.css
|
|
||||||
├── types/
|
|
||||||
│ └── container.type.ts
|
|
||||||
├── container.ui.tsx
|
|
||||||
└── index.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
## Именования
|
|
||||||
|
|
||||||
- Имя корневого css класса всегда `.root`
|
|
||||||
- Тип пропсов именуется `{ComponentName}Props`.
|
|
||||||
- Тип пользовательских параметров именуется `{ComponentName}Params`.
|
|
||||||
|
|
||||||
## Типизация
|
|
||||||
|
|
||||||
Структура типов компонента показана в [примере](#пример). Ниже — обоснования ключевых решений.
|
|
||||||
|
|
||||||
- **`type` вместо `interface`** — гибче для пропсов: поддерживает union, intersection, mapped types. Declaration merging пропсам не нужно.
|
|
||||||
- **Без `FC`** — неявно добавляет `children`, усложняет дженерики, не даёт преимуществ перед аннотацией параметра.
|
|
||||||
- **Типы в `types/`, а не в `.tsx`** — предотвращает циклические зависимости (компонент импортирует хук, хук импортирует тип из компонента) и разделяет ответственность: `.tsx` для рендера, `.type.ts` для данных.
|
|
||||||
- **Без возвращаемого типа** — TypeScript выводит из JSX. Осознанное исключение из [базового правила](/basics/typing).
|
|
||||||
|
|
||||||
## Реализация
|
|
||||||
|
|
||||||
- Пропсы деструктурируются в теле компонента, не в параметрах.
|
|
||||||
- Порядок: пользовательские → системные (`children`, `className`) → `...htmlAttr`.
|
|
||||||
- `className` объединяется с корневым классом через `cl()`: `cl(styles.root, className)`.
|
|
||||||
- `...htmlAttr` прокидывается на корневой элемент.
|
|
||||||
|
|
||||||
## Пример
|
|
||||||
|
|
||||||
`container/types/container.type.ts`
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры компонента Container.
|
|
||||||
*/
|
|
||||||
export type ContainerParams = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type ContainerProps = RootAttrs & ContainerParams
|
|
||||||
```
|
|
||||||
|
|
||||||
`container/styles/container.module.css`
|
|
||||||
|
|
||||||
```css
|
|
||||||
.root {
|
|
||||||
max-width: var(--content-width);
|
|
||||||
margin: 0 auto;
|
|
||||||
padding: 0 var(--spacing-4);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`container/container.ui.tsx`
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
import cl from 'clsx'
|
|
||||||
import type { ContainerProps } from './types/container.type'
|
|
||||||
import styles from './styles/container.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Контейнер с адаптивной максимальной шириной.
|
|
||||||
*
|
|
||||||
* Используется для:
|
|
||||||
* - обёртки контента страниц с ограничением ширины
|
|
||||||
* - центрирования блоков в лейауте
|
|
||||||
*/
|
|
||||||
export const Container = (props: ContainerProps) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`container/index.ts`
|
|
||||||
|
|
||||||
```ts
|
|
||||||
export { Container } from './container.ui'
|
|
||||||
```
|
|
||||||
|
|
||||||
## Дочерние компоненты
|
|
||||||
|
|
||||||
Если модулю нужны внутренние подкомпоненты — генерировать их из шаблона `component` в папку `ui/` внутри родительского модуля. Дочерние компоненты не экспортируются через `index.ts` родителя.
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
scope: applied
|
|
||||||
keywords: [шрифт, font, next/font, подключение шрифта, woff]
|
|
||||||
when: "Подключение и настройка шрифтов"
|
|
||||||
---
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
scope: applied
|
|
||||||
keywords: [хук, hook, use, кастомный хук, useState, useEffect]
|
|
||||||
when: "Создание или использование кастомных хуков"
|
|
||||||
---
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
scope: applied
|
|
||||||
keywords: [изображение, картинка, image, next/image, public, оптимизация]
|
|
||||||
when: "Работа с изображениями: подключение, оптимизация"
|
|
||||||
---
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
scope: applied
|
|
||||||
keywords: [i18n, локализация, перевод, язык, i18next, namespace]
|
|
||||||
when: "Локализация: добавление переводов, работа с i18next"
|
|
||||||
---
|
|
||||||
@@ -1,68 +0,0 @@
|
|||||||
---
|
|
||||||
title: Файлы роутинга
|
|
||||||
scope: applied
|
|
||||||
keywords: [page.tsx, layout.tsx, error.tsx, not-found.tsx, loading.tsx, App Router, metadata]
|
|
||||||
when: "Работа с файлами роутинга Next.js App Router: page, layout, error, not-found"
|
|
||||||
---
|
|
||||||
# Файлы роутинга
|
|
||||||
|
|
||||||
Правила для специальных файлов App Router (`page.tsx`, `layout.tsx`, `error.tsx`, `not-found.tsx` и др.) — чем наш подход отличается от дефолтного.
|
|
||||||
|
|
||||||
## Что нужно знать
|
|
||||||
|
|
||||||
Страница в проекте — это два файла: экран в `src/screens/` (вся логика, стили, зависимости) и `page.tsx` в `src/app/` (точка входа для роутинга Next.js). Экран генерируется из шаблона, `page.tsx` создаётся вручную.
|
|
||||||
|
|
||||||
## Организация
|
|
||||||
|
|
||||||
- `page.tsx` — тонкий файл: только `metadata` и рендер экрана. Логика, стили и зависимости живут в экране, не в `page.tsx`.
|
|
||||||
- `error.tsx` и `not-found.tsx` делегируют разметку экранам по тому же принципу.
|
|
||||||
- `layout.tsx` — точка подключения провайдеров и глобальных стилей. Вёрстка layout-обёрток выносится в слой `layouts/`.
|
|
||||||
- Стили в файлах роутинга не используются — стилизация только внутри вызываемых компонентов.
|
|
||||||
|
|
||||||
## Реализация
|
|
||||||
|
|
||||||
- Каждый `page.tsx` экспортирует `metadata` с `title` — он подставляется в шаблон корневого layout (`%s | App`).
|
|
||||||
- Корневой `layout.tsx` задаёт `metadata` с `title.template`, `description`, `metadataBase` и OpenGraph-настройками.
|
|
||||||
|
|
||||||
## Примеры
|
|
||||||
|
|
||||||
`src/app/profile/[id]/page.tsx`
|
|
||||||
|
|
||||||
```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} />
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`src/app/error.tsx`
|
|
||||||
|
|
||||||
```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
|
|
||||||
```
|
|
||||||
@@ -1,101 +0,0 @@
|
|||||||
---
|
|
||||||
title: Структура проекта
|
|
||||||
scope: applied
|
|
||||||
keywords: [структура проекта, папки, src/app, src/shared, SLM Design, Next.js структура]
|
|
||||||
when: "Организация папок и файлов в Next.js проекте"
|
|
||||||
---
|
|
||||||
# Структура проекта
|
|
||||||
|
|
||||||
Раздел описывает расположение файлов и папок в проекте Next.js (App Router).
|
|
||||||
|
|
||||||
## Корень репозитория
|
|
||||||
|
|
||||||
```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)
|
|
||||||
├── infrastructure/ # Техсервисы (theme, i18n, API-адаптеры)
|
|
||||||
├── ui/ # UI-кит без бизнес-логики (button, modal, toast)
|
|
||||||
└── shared/ # Общие ресурсы (утилиты, типы, стили)
|
|
||||||
```
|
|
||||||
|
|
||||||
Принципы организации слоёв описаны в разделе [Архитектура](../basics/architecture).
|
|
||||||
|
|
||||||
### Папка `app/`
|
|
||||||
|
|
||||||
Точка входа приложения. Совмещает инициализацию (провайдеры, глобальные стили) и файловый роутинг Next.js (`layout.tsx`, `page.tsx`, route-сегменты).
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/app/
|
|
||||||
├── providers/ # Провайдеры приложения
|
|
||||||
├── styles/ # Глобальные стили
|
|
||||||
├── layout.tsx # Корневой layout
|
|
||||||
└── page.tsx # Главная страница
|
|
||||||
```
|
|
||||||
|
|
||||||
## Папка `.templates/`
|
|
||||||
|
|
||||||
Содержит шаблоны для генерации кода. Каждый подкаталог — шаблон отдельного типа модуля:
|
|
||||||
|
|
||||||
```text
|
|
||||||
.templates/
|
|
||||||
├── component/ # Шаблон компонента
|
|
||||||
├── screen/ # Шаблон экрана
|
|
||||||
├── layout/ # Шаблон layout
|
|
||||||
├── widget/ # Шаблон виджета
|
|
||||||
├── business/ # Шаблон бизнес-модуля
|
|
||||||
└── store/ # Шаблон стора
|
|
||||||
```
|
|
||||||
|
|
||||||
Подробнее о генерации описано в разделе [Шаблоны и генерация кода](./templates-generation).
|
|
||||||
|
|
||||||
## Конфигурационные файлы
|
|
||||||
|
|
||||||
| Файл | Назначение |
|
|
||||||
|---|---|
|
|
||||||
| `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_` доступны в клиентском коде. Остальные доступны только на сервере.
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
scope: applied
|
|
||||||
keywords: [стор, store, zustand, состояние, глобальное состояние]
|
|
||||||
when: "Работа с глобальным состоянием: создание стора, подписка"
|
|
||||||
---
|
|
||||||
@@ -1,285 +0,0 @@
|
|||||||
---
|
|
||||||
title: Стили
|
|
||||||
scope: applied
|
|
||||||
keywords: [css, postcss, модули, css modules, токены, медиа-запросы, вложенность, класс]
|
|
||||||
when: "Стилизация: CSS Modules, PostCSS, переменные, медиа-запросы"
|
|
||||||
---
|
|
||||||
# Стили
|
|
||||||
|
|
||||||
Раздел описывает правила написания CSS: PostCSS Modules, вложенность, медиа-запросы, переменные, форматирование.
|
|
||||||
|
|
||||||
## Общие правила
|
|
||||||
|
|
||||||
- Только **PostCSS** и **CSS Modules** для кастомной стилизации.
|
|
||||||
- Подход **Mobile First** — стили пишутся от мобильных к десктопу.
|
|
||||||
- Именование классов — `camelCase` (`.root`, `.buttonNext`, `.itemTitle`).
|
|
||||||
- Модификаторы — отдельный класс с `_`, применяется через `&._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-*`) определяются в `app/styles/variables.css` через `:root`.
|
|
||||||
- Файл переменных подключается один раз в корневом layout/entry point — после этого переменные доступны глобально через каскад.
|
|
||||||
- Не дублировать магические значения в компонентах.
|
|
||||||
|
|
||||||
**Хорошо**
|
|
||||||
```css
|
|
||||||
/* app/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 в `app/styles/media.css`.
|
|
||||||
- Custom media подключаются глобально через конфиг PostCSS (плагин `postcss-custom-media`) — не импортировать в файлы стилей.
|
|
||||||
|
|
||||||
```css
|
|
||||||
/* app/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.
|
|
||||||
- Исключение — нетривиальные хаки и обходные решения, к которым стоит оставить пояснение.
|
|
||||||
|
|
||||||
## Приоритет стилизации
|
|
||||||
|
|
||||||
Основной UI-фреймворк проекта — **Mantine**. При стилизации компонентов придерживаться следующего приоритета:
|
|
||||||
|
|
||||||
1. **Mantine-компоненты и их пропсы** — в первую очередь использовать встроенные возможности Mantine (пропсы, `classNames`, `styles`).
|
|
||||||
2. **Глобальные CSS-токены** (`--color-*`, `--space-*`, `--radius-*`) — для значений, которые не покрываются Mantine.
|
|
||||||
3. **PostCSS Modules** — когда Mantine не покрывает задачу и нужна кастомная стилизация.
|
|
||||||
|
|
||||||
## Что запрещено
|
|
||||||
|
|
||||||
- **Инлайн-стили** — использование атрибута `style` в компонентах строго запрещено.
|
|
||||||
- **Магические значения** — произвольные цвета, отступы и скругления запрещены, использовать токены.
|
|
||||||
- **Глобальные стили** вне `app/styles/` запрещены.
|
|
||||||
@@ -1,7 +0,0 @@
|
|||||||
---
|
|
||||||
title: SVG-спрайты
|
|
||||||
scope: applied
|
|
||||||
keywords: [svg, спрайт, иконка, icon, sprite]
|
|
||||||
when: "Работа с SVG-иконками и спрайтами"
|
|
||||||
---
|
|
||||||
# SVG-спрайты
|
|
||||||
@@ -1,174 +0,0 @@
|
|||||||
---
|
|
||||||
title: Шаблоны и генерация кода
|
|
||||||
scope: applied
|
|
||||||
keywords: [шаблон, генерация, template, scaffold, plop, hygen, .templates]
|
|
||||||
when: "Генерация кода из шаблонов, создание новых шаблонов"
|
|
||||||
---
|
|
||||||
<!-- @formatter:off -->
|
|
||||||
::: v-pre
|
|
||||||
|
|
||||||
# Шаблоны и генерация кода
|
|
||||||
|
|
||||||
Как работают шаблоны, как их создавать, синтаксис переменных и как генерировать код с помощью расширения VS Code и CLI.
|
|
||||||
|
|
||||||
## Структура шаблонов
|
|
||||||
|
|
||||||
Все шаблоны лежат в `.templates/` в корне проекта. Каждая папка — отдельный шаблон.
|
|
||||||
|
|
||||||
```text
|
|
||||||
.templates/
|
|
||||||
├── component/ # шаблон компонента
|
|
||||||
│ └── {{name.kebabCase}}/
|
|
||||||
│ ├── styles/
|
|
||||||
│ │ └── {{name.kebabCase}}.module.css
|
|
||||||
│ ├── types/
|
|
||||||
│ │ └── {{name.kebabCase}}.type.ts
|
|
||||||
│ ├── {{name.kebabCase}}.tsx
|
|
||||||
│ └── index.ts
|
|
||||||
└── store/ # шаблон Zustand стора
|
|
||||||
└── {{name.kebabCase}}/
|
|
||||||
├── {{name.kebabCase}}.store.ts
|
|
||||||
├── {{name.kebabCase}}.type.ts
|
|
||||||
└── index.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
## Синтаксис шаблонов
|
|
||||||
|
|
||||||
Переменные работают в именах файлов/папок и внутри файлов. Базовая переменная — `name`.
|
|
||||||
|
|
||||||
```text
|
|
||||||
{{variable}}
|
|
||||||
```
|
|
||||||
|
|
||||||
Модификаторы меняют регистр и формат записи:
|
|
||||||
|
|
||||||
```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'
|
|
||||||
```
|
|
||||||
|
|
||||||
## Примеры шаблонов
|
|
||||||
|
|
||||||
### Шаблон компонента
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// .templates/component/index.ts
|
|
||||||
export { {{name.pascalCase}} } from './{{name.kebabCase}}'
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// .templates/component/types/{{name.kebabCase}}.type.ts
|
|
||||||
import type { HTMLAttributes } from 'react'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Параметры {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export type {{name.pascalCase}}Params = {}
|
|
||||||
|
|
||||||
/** HTML-атрибуты корневого элемента. */
|
|
||||||
type RootAttrs = HTMLAttributes<HTMLDivElement>
|
|
||||||
|
|
||||||
export type {{name.pascalCase}}Props = RootAttrs & {{name.pascalCase}}Params
|
|
||||||
```
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
// .templates/component/{{name.kebabCase}}.tsx
|
|
||||||
import cl from 'clsx'
|
|
||||||
import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.type'
|
|
||||||
import styles from './styles/{{name.kebabCase}}.module.css'
|
|
||||||
|
|
||||||
/**
|
|
||||||
* {{name.pascalCase}}.
|
|
||||||
*/
|
|
||||||
export const {{name.pascalCase}} = (props: {{name.pascalCase}}Props) => {
|
|
||||||
const { children, className, ...htmlAttr } = props
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
|
||||||
{children}
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```css
|
|
||||||
/* .templates/component/styles/{{name.kebabCase}}.module.css */
|
|
||||||
.root {
|
|
||||||
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Генерация через 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 src/ui` | Компонент |
|
|
||||||
| `npx @gromlab/create business auth src/business` | Бизнес-модуль |
|
|
||||||
| `npx @gromlab/create widget header src/widgets` | Виджет |
|
|
||||||
| `npx @gromlab/create layout admin src/layouts` | Layout |
|
|
||||||
| `npx @gromlab/create screen home src/screens` | Экран |
|
|
||||||
| `npx @gromlab/create store auth src/business/auth/stores` | Стор |
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Какие модули генерируются из шаблонов
|
|
||||||
|
|
||||||
| Модуль | Слой | Шаблон |
|
|
||||||
|---|---|---|
|
|
||||||
| Компонент | `ui/` | `component` |
|
|
||||||
| Бизнес-модуль | `business/` | `business` |
|
|
||||||
| Виджет | `widgets/` | `widget` |
|
|
||||||
| Layout | `layouts/` | `layout` |
|
|
||||||
| Экран | `screens/` | `screen` |
|
|
||||||
| Стор | `stores/` | `store` |
|
|
||||||
|
|
||||||
## Когда создавать новый шаблон
|
|
||||||
|
|
||||||
- Повторяющаяся структура появляется больше одного раза.
|
|
||||||
- Существующий шаблон не покрывает нужный тип модуля.
|
|
||||||
|
|
||||||
@@ -1,5 +0,0 @@
|
|||||||
---
|
|
||||||
scope: applied
|
|
||||||
keywords: [видео, video, плеер, mp4]
|
|
||||||
when: "Встраивание и работа с видео"
|
|
||||||
---
|
|
||||||
@@ -1,89 +0,0 @@
|
|||||||
---
|
|
||||||
title: Настройка VS Code
|
|
||||||
scope: applied
|
|
||||||
keywords: [vscode, редактор, расширение, настройка, extension, .vscode]
|
|
||||||
when: "Настройка VS Code: расширения, settings.json, сниппеты"
|
|
||||||
---
|
|
||||||
# Настройка VS Code
|
|
||||||
|
|
||||||
Каждый проект содержит папку `.vscode/` с конфигурацией редактора. Это гарантирует, что все участники команды работают с одинаковыми настройками форматирования, линтинга и расширениями.
|
|
||||||
|
|
||||||
## Структура `.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` с общими для команды настройками.
|
|
||||||
@@ -1,665 +0,0 @@
|
|||||||
---
|
|
||||||
title: Архитектура
|
|
||||||
scope: basics
|
|
||||||
keywords: [SLM Design, слой, модуль, сегмент, архитектура, FSD, scoped layered module]
|
|
||||||
when: "Организация кода: слои, модули, зависимости между модулями"
|
|
||||||
---
|
|
||||||
|
|
||||||
<!-- /index -->
|
|
||||||
# SLM Design
|
|
||||||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
|
||||||
|
|
||||||
## Преимущества
|
|
||||||
|
|
||||||
### Вертикальная организация домена
|
|
||||||
|
|
||||||
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы и UI живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: все изменения домена локализованы.
|
|
||||||
|
|
||||||
### Dependency Injection без фреймворков
|
|
||||||
|
|
||||||
Cross-domain зависимости в бизнес-слое реализуются через фабрики — модуль декларирует что ему нужно, а точка использования предоставляет зависимости. Домены изолированы без DI-контейнеров, провайдеров и шин событий.
|
|
||||||
|
|
||||||
### Разделение ответственности без перегрузки слоёв
|
|
||||||
|
|
||||||
Сервисы приложения (`infrastructure/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — три разных слоя с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
|
||||||
|
|
||||||
### Горизонтальная инкапсуляция
|
|
||||||
|
|
||||||
Вложенные модули (`parts/`) и направление зависимостей позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
|
|
||||||
|
|
||||||
### Колокация по умолчанию
|
|
||||||
|
|
||||||
Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
|
|
||||||
|
|
||||||
### Явное разделение каркаса и контента
|
|
||||||
|
|
||||||
Каркас группы маршрутов (`layouts/`) и контент конкретной страницы (`screens/`) — независимые слои с собственной ответственностью.
|
|
||||||
|
|
||||||
### Масштабирование через группировку
|
|
||||||
|
|
||||||
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: бизнес-домены по субдоменам, страницы по разделам, UI-компоненты по уровню абстракции (примитивы и композиции).
|
|
||||||
|
|
||||||
## Происхождение
|
|
||||||
|
|
||||||
SLM Design вырос на основе:
|
|
||||||
|
|
||||||
- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
|
|
||||||
- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
|
|
||||||
- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
|
|
||||||
- **Colocation Principle** — код живёт рядом с местом использования
|
|
||||||
|
|
||||||
## Пример структуры проекта
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/
|
|
||||||
├── app/
|
|
||||||
│
|
|
||||||
├── layouts/
|
|
||||||
│ ├── main/
|
|
||||||
│ └── dashboard/
|
|
||||||
│
|
|
||||||
├── screens/
|
|
||||||
│ ├── home/
|
|
||||||
│ ├── products/
|
|
||||||
│ ├── product-detail/
|
|
||||||
│ └── about/
|
|
||||||
│
|
|
||||||
├── widgets/
|
|
||||||
│ ├── page-heading/
|
|
||||||
│ ├── hero-section/
|
|
||||||
│ └── promo-banner/
|
|
||||||
│
|
|
||||||
├── business/
|
|
||||||
│ ├── auth/
|
|
||||||
│ ├── catalog/
|
|
||||||
│ ├── orders/
|
|
||||||
│ └── chat/
|
|
||||||
│
|
|
||||||
├── infrastructure/
|
|
||||||
│ ├── theme/
|
|
||||||
│ ├── i18n/
|
|
||||||
│ ├── backend-api/
|
|
||||||
│ └── logger/
|
|
||||||
│
|
|
||||||
├── ui/
|
|
||||||
│ ├── button/
|
|
||||||
│ ├── input/
|
|
||||||
│ ├── modal/
|
|
||||||
│ ├── toast/
|
|
||||||
│ └── dropdown/
|
|
||||||
│
|
|
||||||
└── shared/
|
|
||||||
├── lib/
|
|
||||||
├── types/
|
|
||||||
└── styles/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Принципы
|
|
||||||
|
|
||||||
- **Домен — единое целое.** Всё, что относится к домену, живёт в одном модуле.
|
|
||||||
- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
|
|
||||||
- **Зависимости однонаправлены.** Импорты только сверху вниз, только через публичный API.
|
|
||||||
- **Архитектура — каркас, не клетка.** Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.
|
|
||||||
|
|
||||||
<!-- /reference/layers -->
|
|
||||||
## Слои
|
|
||||||
|
|
||||||
Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом.
|
|
||||||
|
|
||||||
### Определение
|
|
||||||
|
|
||||||
**Слой — уровень организации кода внутри `src/`. Каждый слой отвечает за свою область (каркас страницы, бизнес-логика, UI-кит) и задаёт правила для кода внутри: направление импортов, именование, допустимые связи между модулями.**
|
|
||||||
|
|
||||||
### Группы слоёв
|
|
||||||
|
|
||||||
Слои делятся на три группы:
|
|
||||||
|
|
||||||
| Группа | Слои | Описание |
|
|
||||||
|--------|------|----------|
|
|
||||||
| Композиция | `app`, `layouts`, `screens`, `widgets` | Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы |
|
|
||||||
| Ядро | `business`, `infrastructure`, `ui` | Реализация продукта: бизнес-домены, техсервисы, UI-кит |
|
|
||||||
| Фундамент | `shared` | Общие ресурсы: утилиты, хелперы, стили, конфиги |
|
|
||||||
|
|
||||||
### Направление зависимостей
|
|
||||||
|
|
||||||
Любой импорт между модулями — только через публичный API.
|
|
||||||
|
|
||||||
```
|
|
||||||
app → [ layouts | screens ] → widgets → business → infrastructure → ui → shared
|
|
||||||
```
|
|
||||||
|
|
||||||
- `layouts` и `screens` — параллельные слои, не импортируют друг друга
|
|
||||||
- Модули одного слоя в группе «Композиция» изолированы друг от друга
|
|
||||||
- Модули одного слоя `infrastructure` и `ui` могут импортировать друг друга через публичный API
|
|
||||||
- Модули `business` — cross-domain зависимости по коду через фабрику, `import type` напрямую
|
|
||||||
- Импорт типов (`import type`) в «Ядре» разрешён в обоих направлениях
|
|
||||||
|
|
||||||
|
|
||||||
### Слой App
|
|
||||||
|
|
||||||
Точка входа приложения. Отвечает за запуск, роутинг и композицию маршрутов из layout и screen.
|
|
||||||
|
|
||||||
В отличие от остальных слоёв, `app/` не содержит модулей SLM. Здесь живут только инфраструктурные файлы, которые не могут быть никаким другим слоем: файлы фреймворка роутинга, точка запуска и код инициализации.
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Не содержит модулей SLM — только файлы фреймворка, роутинг, инициализация
|
|
||||||
- Содержит: файлы маршрутов, bootstrap, обработку ошибок верхнего уровня (404, error boundary), подключение глобальных стилей и ассетов
|
|
||||||
- Провайдеры и гарды — только подключает готовые из нижних слоёв, не реализует
|
|
||||||
- Не содержит бизнес-логику, UI-компоненты, хуки, сторы, сервисы
|
|
||||||
- Никем не импортируется
|
|
||||||
|
|
||||||
### Слой Layouts
|
|
||||||
|
|
||||||
Каркас страницы: общие элементы, одинаковые для группы маршрутов (header, footer, sidebar).
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/layouts/
|
|
||||||
├── main/
|
|
||||||
├── dashboard/
|
|
||||||
└── auth/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Содержит только модули
|
|
||||||
- Не содержит бизнес-логику
|
|
||||||
- Контекстно-зависимые блоки принимает через пропсы от `app`, не импортирует напрямую
|
|
||||||
|
|
||||||
### Слой Screens
|
|
||||||
|
|
||||||
Контент конкретной страницы: собирает её из модулей нижних слоёв.
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/screens/
|
|
||||||
├── home/
|
|
||||||
├── products/
|
|
||||||
├── product-detail/
|
|
||||||
├── about/
|
|
||||||
└── contacts/
|
|
||||||
```
|
|
||||||
|
|
||||||
Когда количество страниц затрудняет навигацию — вводится группировка по разделам. Группа — папка для организации, не модуль (без `index.ts`).
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/screens/
|
|
||||||
├── shop/
|
|
||||||
│ ├── home/
|
|
||||||
│ ├── products/
|
|
||||||
│ ├── product-detail/
|
|
||||||
│ └── cart/
|
|
||||||
├── account/
|
|
||||||
│ ├── profile/
|
|
||||||
│ ├── settings/
|
|
||||||
│ └── order-history/
|
|
||||||
└── info/
|
|
||||||
├── about/
|
|
||||||
├── contacts/
|
|
||||||
└── faq/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Содержит только модули
|
|
||||||
- Не содержит бизнес-логику
|
|
||||||
- Локальные одноразовые секции живут внутри screen-модуля, не выносятся в `widgets`/`business`
|
|
||||||
|
|
||||||
### Слой Widgets
|
|
||||||
|
|
||||||
Составной блок интерфейса, который компонует модули ядра, но не принадлежит конкретному бизнес-домену. Widget появляется когда блок используется в нескольких screens или layouts.
|
|
||||||
|
|
||||||
Если блок принадлежит домену — он живёт в `business/{area}/`, даже если переиспользуется. Если блок нужен только в одном месте — это `screens/{name}/parts/` или `layouts/{name}/parts/`, а не widget.
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/widgets/
|
|
||||||
├── page-heading/
|
|
||||||
├── hero-section/
|
|
||||||
├── onboarding-checklist/
|
|
||||||
├── promo-banner/
|
|
||||||
└── error-boundary/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Не принадлежит конкретному бизнес-домену. Если блок доменный — он живёт в `business/`
|
|
||||||
- Используется в нескольких screens или layouts
|
|
||||||
|
|
||||||
### Слой Business
|
|
||||||
|
|
||||||
Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.
|
|
||||||
|
|
||||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`. Cross-domain зависимости по коду реализуются через фабрику. `import type` между доменами разрешён напрямую.
|
|
||||||
|
|
||||||
Business объединяет то, что в FSD разделено на `features` и `entities`: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: `types/` — доменная модель, `hooks/` и `services/` — сценарии и логика, `mappers/` — трансформация данных, `parts/` — составные блоки.
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/business/
|
|
||||||
├── auth/
|
|
||||||
├── catalog/
|
|
||||||
├── orders/
|
|
||||||
├── checkout/
|
|
||||||
└── chat/
|
|
||||||
```
|
|
||||||
|
|
||||||
Когда количество доменов затрудняет навигацию — вводится группировка по субдоменам. Группа — папка для организации, не модуль (без `index.ts`).
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/business/
|
|
||||||
├── commerce/
|
|
||||||
│ ├── catalog/
|
|
||||||
│ ├── cart/
|
|
||||||
│ ├── orders/
|
|
||||||
│ └── checkout/
|
|
||||||
└── communication/
|
|
||||||
├── chat/
|
|
||||||
└── notifications/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Один модуль = один бизнес-домен
|
|
||||||
- Циклические зависимости между доменами запрещены
|
|
||||||
- Импорт кода между доменами — через фабрику. `import type` — напрямую
|
|
||||||
- Доменные типы (`User`, `Product`) живут здесь, не в `shared/`
|
|
||||||
|
|
||||||
### Слой Infrastructure
|
|
||||||
|
|
||||||
Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.
|
|
||||||
|
|
||||||
Слой входит в группу «Ядро». Импортирует `infrastructure/`, `ui/`, `shared/`.
|
|
||||||
|
|
||||||
Отличие от `shared/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/infrastructure/
|
|
||||||
├── theme/
|
|
||||||
├── i18n/
|
|
||||||
├── backend-api/
|
|
||||||
├── maps-api/
|
|
||||||
├── logger/
|
|
||||||
├── feature-flags/
|
|
||||||
└── realtime/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Один модуль = один техсервис
|
|
||||||
- Импортирует `infrastructure/`, `ui/`, `shared/`
|
|
||||||
|
|
||||||
### Слой UI
|
|
||||||
|
|
||||||
UI-кит без бизнес-логики: button, carousel, toast, modal.
|
|
||||||
|
|
||||||
Слой входит в группу «Ядро». Импортирует `ui/` и `shared/`.
|
|
||||||
|
|
||||||
Компоненты строятся друг на друге: `button` использует `icon`, `carousel` использует `button`.
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/ui/
|
|
||||||
├── button/
|
|
||||||
├── input/
|
|
||||||
├── icon/
|
|
||||||
├── carousel/
|
|
||||||
├── modal/
|
|
||||||
├── toast/
|
|
||||||
├── dropdown/
|
|
||||||
├── tabs/
|
|
||||||
└── tooltip/
|
|
||||||
```
|
|
||||||
|
|
||||||
Когда количество компонентов затрудняет навигацию — вводится группировка на примитивы и композиции. Примитивы (`button`, `icon`, `input`) не импортируют композиции. Композиции (`carousel`, `modal`, `dropdown`) строятся на примитивах.
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/ui/
|
|
||||||
├── primitives/
|
|
||||||
│ ├── button/
|
|
||||||
│ ├── input/
|
|
||||||
│ ├── icon/
|
|
||||||
│ └── badge/
|
|
||||||
└── composites/
|
|
||||||
├── carousel/
|
|
||||||
├── modal/
|
|
||||||
├── dropdown/
|
|
||||||
├── tabs/
|
|
||||||
└── tooltip/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Не содержит бизнес-логику
|
|
||||||
- Импортирует только `ui/` и `shared/`
|
|
||||||
|
|
||||||
### Слой Shared
|
|
||||||
|
|
||||||
Общие ресурсы: утилиты, хелперы, стили, конфиги. Не знает о бизнес-домене.
|
|
||||||
|
|
||||||
Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.
|
|
||||||
|
|
||||||
Отличие от `infrastructure/`: infrastructure — инфраструктура приложения (сервисы, темы, адаптеры к API), `shared/` — общие ресурсы (утилиты, хелперы, стили, конфиги).
|
|
||||||
|
|
||||||
Отличие от `ui/`: UI-компоненты (button, carousel, modal) живут в слое `ui/`, а не здесь.
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/shared/
|
|
||||||
├── lib/
|
|
||||||
├── types/
|
|
||||||
├── styles/
|
|
||||||
└── sprites/
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Требования
|
|
||||||
|
|
||||||
- Не имеет runtime-состояния
|
|
||||||
|
|
||||||
<!-- /reference/modules -->
|
|
||||||
## Модули
|
|
||||||
|
|
||||||
Раздел описывает модули SLM: что такое модуль, из чего он состоит и как взаимодействует с остальным кодом.
|
|
||||||
|
|
||||||
### Определение
|
|
||||||
|
|
||||||
**Модуль — универсальный строительный блок архитектуры. Живёт на слое и содержит всё необходимое для своей работы: компоненты, хуки, сторы, сервисы, типы, стили. Набор содержимого не фиксирован — включаются только нужные части.**
|
|
||||||
|
|
||||||
### Модуль vs компонент
|
|
||||||
|
|
||||||
**Компонент** — один `.tsx` файл. Не имеет своих сегментов, использует сегменты родительского модуля. Живёт в корне или `ui/` сегменте модуля.
|
|
||||||
|
|
||||||
**Модуль** — папка, которая может содержать корневой компонент, сегменты (`hooks/`, `types/`, `styles/`, `ui/`, `parts/` и т.д.) и публичный API (`index.ts`).
|
|
||||||
|
|
||||||
```text
|
|
||||||
auth/
|
|
||||||
├── ui/
|
|
||||||
│ ├── auth-guard.tsx
|
|
||||||
│ └── logout-button.tsx
|
|
||||||
├── parts/
|
|
||||||
│ ├── login-form/
|
|
||||||
│ ├── registration-form/
|
|
||||||
│ └── restore-form/
|
|
||||||
├── hooks/
|
|
||||||
├── stores/
|
|
||||||
├── types/
|
|
||||||
├── auth.tsx # корневой компонент (опционален)
|
|
||||||
└── index.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
### Структура
|
|
||||||
|
|
||||||
Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль может состоять даже из одного `index.ts` с реэкспортом типов.
|
|
||||||
|
|
||||||
```text
|
|
||||||
{module-name}/
|
|
||||||
├── {module-name}.tsx # корневой компонент (опционален)
|
|
||||||
├── ui/ # компоненты модуля (только .tsx)
|
|
||||||
├── parts/ # вложенные модули (со своими сегментами)
|
|
||||||
├── hooks/ # хуки
|
|
||||||
├── stores/ # сторы состояния
|
|
||||||
├── services/ # внешние источники данных
|
|
||||||
├── mappers/ # трансформация данных между форматами
|
|
||||||
├── types/ # типы
|
|
||||||
├── styles/ # стили
|
|
||||||
├── lib/ # утилиты модуля
|
|
||||||
├── config/ # константы
|
|
||||||
└── index.ts # публичный API
|
|
||||||
```
|
|
||||||
|
|
||||||
Подробное описание каждого сегмента — в разделе [Сегменты](/reference/segments).
|
|
||||||
|
|
||||||
### Публичный API
|
|
||||||
|
|
||||||
Модуль экспортирует наружу только то, что нужно другим. Всё остальное — внутреннее.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/auth/index.ts
|
|
||||||
export type { User, Session } from './types/user.types'
|
|
||||||
export { useAuth } from './hooks/use-auth.hook'
|
|
||||||
export { AuthGuard } from './ui/auth-guard'
|
|
||||||
```
|
|
||||||
|
|
||||||
Импорт в обход `index.ts` запрещён:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// Плохо
|
|
||||||
import { validateToken } from '@/business/auth/lib/tokens'
|
|
||||||
|
|
||||||
// Хорошо
|
|
||||||
import { useAuth } from '@/business/auth'
|
|
||||||
```
|
|
||||||
|
|
||||||
### Фабрика
|
|
||||||
|
|
||||||
Если модуль зависит от кода другого бизнес-домена — он экспортирует фабрику. Фабрика декларирует необходимые зависимости и возвращает API модуля. Точка использования (screen, widget, layout) предоставляет зависимости при вызове.
|
|
||||||
|
|
||||||
Модуль без cross-domain зависимостей экспортирует API напрямую. Типы всегда экспортируются напрямую — `import type` не является runtime-зависимостью.
|
|
||||||
|
|
||||||
#### Модуль без зависимостей — прямой экспорт:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/auth/index.ts
|
|
||||||
export { useAuth } from './hooks/use-auth'
|
|
||||||
export { useCurrentUser } from './hooks/use-current-user'
|
|
||||||
export type { User, Session } from './types'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Модуль с зависимостями — фабрика:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/chat/types/deps.ts
|
|
||||||
import type { User } from '@/business/auth'
|
|
||||||
|
|
||||||
export interface ChatDeps {
|
|
||||||
useCurrentUser: () => User | null
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// business/chat/index.ts
|
|
||||||
import type { ChatDeps } from './types/deps'
|
|
||||||
|
|
||||||
export function chatFactory(deps: ChatDeps) {
|
|
||||||
return {
|
|
||||||
useMessages: (roomId: string) => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
// ...
|
|
||||||
},
|
|
||||||
useSendMessage: (roomId: string) => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
return (text: string) => { /* ... */ }
|
|
||||||
},
|
|
||||||
useChatRooms: () => {
|
|
||||||
const user = deps.useCurrentUser()
|
|
||||||
// ...
|
|
||||||
},
|
|
||||||
ChatBadge: ({ count }: { count: number }) => { /* ... */ },
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export type { Message, ChatRoom } from './types'
|
|
||||||
export type { ChatDeps } from './types/deps'
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Использование на странице:
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
// screens/support/support.tsx
|
|
||||||
import { useCurrentUser } from '@/business/auth'
|
|
||||||
import { chatFactory } from '@/business/chat'
|
|
||||||
|
|
||||||
const chat = chatFactory({ useCurrentUser })
|
|
||||||
|
|
||||||
export function SupportScreen() {
|
|
||||||
const { useMessages, useSendMessage, ChatBadge } = chat
|
|
||||||
const messages = useMessages('support')
|
|
||||||
const sendMessage = useSendMessage('support')
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div>
|
|
||||||
<ChatBadge count={messages.length} />
|
|
||||||
{messages.map(m => <MessageBubble key={m.id} {...m} />)}
|
|
||||||
<MessageInput onSend={sendMessage} />
|
|
||||||
</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Жизненный цикл
|
|
||||||
|
|
||||||
Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.
|
|
||||||
|
|
||||||
- Нужен на одной странице → `screens/{name}/parts/`
|
|
||||||
- Появился в 2+ местах → поднимается по природе:
|
|
||||||
- абстрактный UI → `ui/`
|
|
||||||
- блок с данными/логикой → `widgets/`
|
|
||||||
- представление бизнес-домена → `business/{area}/parts/`
|
|
||||||
|
|
||||||
Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.
|
|
||||||
|
|
||||||
<!-- /reference/segments -->
|
|
||||||
## Сегменты
|
|
||||||
|
|
||||||
Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит.
|
|
||||||
|
|
||||||
### Определение
|
|
||||||
|
|
||||||
**Сегмент — папка внутри модуля, которая группирует файлы по назначению. Набор сегментов не фиксирован — модуль включает только те, которые ему нужны. Команда сама определяет какие сегменты используются в проекте — архитектура даёт рекомендацию.**
|
|
||||||
|
|
||||||
### Обзор
|
|
||||||
|
|
||||||
| Сегмент | Содержимое |
|
|
||||||
|---------|------------|
|
|
||||||
| `ui/` | Компоненты модуля — только `.tsx` файлы |
|
|
||||||
| `parts/` | Вложенные модули со своими сегментами |
|
|
||||||
| `hooks/` | React-хуки |
|
|
||||||
| `stores/` | Сторы состояния |
|
|
||||||
| `services/` | Работа с внешними источниками данных |
|
|
||||||
| `mappers/` | Трансформация данных между форматами |
|
|
||||||
| `types/` | TypeScript-типы и интерфейсы |
|
|
||||||
| `styles/` | Стили |
|
|
||||||
| `lib/` | Утилиты и хелперы модуля |
|
|
||||||
| `config/` | Константы и конфигурация |
|
|
||||||
|
|
||||||
### Сегмент ui/
|
|
||||||
|
|
||||||
Компоненты, принадлежащие модулю. Содержит только `.tsx` файлы — без своих сегментов, стилей, типов, хуков. Использует сегменты родительского модуля.
|
|
||||||
|
|
||||||
```text
|
|
||||||
auth/
|
|
||||||
├── ui/
|
|
||||||
│ ├── auth-provider.tsx
|
|
||||||
│ ├── auth-guard.tsx
|
|
||||||
│ └── logout-button.tsx
|
|
||||||
├── types/
|
|
||||||
├── hooks/
|
|
||||||
└── index.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
Если компоненту нужны собственные сегменты — это уже не `ui/`, а `parts/`.
|
|
||||||
|
|
||||||
### Сегмент parts/
|
|
||||||
|
|
||||||
Вложенные модули со своими сегментами. Каждый элемент `parts/` — полноценный модуль: папка с компонентом, хуками, стилями, типами и т.д.
|
|
||||||
|
|
||||||
```text
|
|
||||||
home/
|
|
||||||
├── parts/
|
|
||||||
│ ├── hero-section/
|
|
||||||
│ │ ├── hero-section.tsx
|
|
||||||
│ │ ├── styles/
|
|
||||||
│ │ └── parts/
|
|
||||||
│ │ └── top-banner/
|
|
||||||
│ │ └── top-banner.tsx
|
|
||||||
│ └── features-section/
|
|
||||||
│ ├── features-section.tsx
|
|
||||||
│ └── hooks/
|
|
||||||
├── home.screen.tsx
|
|
||||||
└── index.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
Отличие от `ui/`: элемент `parts/` — модуль со своими сегментами. Элемент `ui/` — компонент, один `.tsx` файл.
|
|
||||||
|
|
||||||
Вложенность `parts/` инкапсулирует область разработки горизонтально: каждый разработчик работает в своём `parts/`-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.
|
|
||||||
|
|
||||||
Если вложенный модуль обрастает своими `parts/` — это сигнал, что он достаточно самостоятельный для подъёма на уровень выше.
|
|
||||||
|
|
||||||
### Сегмент hooks/
|
|
||||||
|
|
||||||
React-хуки модуля. Инкапсулируют логику, состояние, подписки, побочные эффекты.
|
|
||||||
|
|
||||||
```text
|
|
||||||
hooks/
|
|
||||||
├── use-auth.hook.ts
|
|
||||||
├── use-session.hook.ts
|
|
||||||
└── use-permissions.hook.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
### Сегмент stores/
|
|
||||||
|
|
||||||
Сторы состояния модуля. Конкретная реализация зависит от выбранного стейт-менеджера (Zustand, MobX, Redux и т.д.).
|
|
||||||
|
|
||||||
```text
|
|
||||||
stores/
|
|
||||||
├── auth.store.ts
|
|
||||||
└── session.store.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
### Сегмент services/
|
|
||||||
|
|
||||||
Работа с внешними источниками данных: API-вызовы, запросы, подписки.
|
|
||||||
|
|
||||||
```text
|
|
||||||
services/
|
|
||||||
├── auth.service.ts
|
|
||||||
└── token.service.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
### Сегмент mappers/
|
|
||||||
|
|
||||||
Функции трансформации данных из одного формата в другой: DTO в доменный тип, доменный тип в DTO, доменный тип в ViewModel.
|
|
||||||
|
|
||||||
```text
|
|
||||||
mappers/
|
|
||||||
├── map-user.ts
|
|
||||||
├── map-product.ts
|
|
||||||
└── map-order-to-dto.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
### Сегмент types/
|
|
||||||
|
|
||||||
TypeScript-типы и интерфейсы модуля. Доменные типы, DTO, пропсы компонентов.
|
|
||||||
|
|
||||||
```text
|
|
||||||
types/
|
|
||||||
├── user.type.ts
|
|
||||||
└── session.type.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
### Сегмент styles/
|
|
||||||
|
|
||||||
Стили модуля. Формат зависит от выбранного подхода (CSS Modules, SCSS, CSS-in-JS и т.д.).
|
|
||||||
|
|
||||||
```text
|
|
||||||
styles/
|
|
||||||
├── auth.module.css
|
|
||||||
└── login-form.module.css
|
|
||||||
```
|
|
||||||
|
|
||||||
### Сегмент lib/
|
|
||||||
|
|
||||||
Утилиты и хелперы, специфичные для модуля. Чистые функции без побочных эффектов.
|
|
||||||
|
|
||||||
```text
|
|
||||||
lib/
|
|
||||||
├── validate-email.ts
|
|
||||||
└── format-phone.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
Отличие от `shared/lib/`: здесь лежат утилиты, нужные только этому модулю. Общие утилиты — в `shared/lib/`.
|
|
||||||
|
|
||||||
### Сегмент config/
|
|
||||||
|
|
||||||
Константы и конфигурация модуля: маршруты, лимиты, дефолтные значения.
|
|
||||||
|
|
||||||
```text
|
|
||||||
config/
|
|
||||||
├── routes.ts
|
|
||||||
└── constants.ts
|
|
||||||
```
|
|
||||||
@@ -1,154 +0,0 @@
|
|||||||
---
|
|
||||||
title: Стиль кода
|
|
||||||
scope: basics
|
|
||||||
keywords: [форматирование, импорт, отступ, кавычки, early return, точка с запятой, линтер]
|
|
||||||
when: "Написание или ревью любого кода: форматирование, импорты, структура файла"
|
|
||||||
---
|
|
||||||
# Стиль кода
|
|
||||||
|
|
||||||
Раздел описывает единые правила оформления кода: отступы, переносы, кавычки, порядок импортов и базовую читаемость.
|
|
||||||
|
|
||||||
## Отступы
|
|
||||||
|
|
||||||
- 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 } };
|
|
||||||
```
|
|
||||||
@@ -1,136 +0,0 @@
|
|||||||
---
|
|
||||||
title: Документирование
|
|
||||||
scope: basics
|
|
||||||
keywords: [JSDoc, комментарий, документирование, описание функции, описание компонента]
|
|
||||||
when: "Документирование кода: JSDoc для функций, компонентов, типов"
|
|
||||||
---
|
|
||||||
# Документирование
|
|
||||||
|
|
||||||
Этот раздел описывает правила документирования кода: когда и как писать
|
|
||||||
комментарии к компонентам, функциям, типам и интерфейсам.
|
|
||||||
|
|
||||||
## Общие правила
|
|
||||||
|
|
||||||
- Документировать публичные функции, компоненты, типы, интерфейсы и 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;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
@@ -1,149 +0,0 @@
|
|||||||
---
|
|
||||||
title: Именование
|
|
||||||
scope: basics
|
|
||||||
keywords: [camelCase, kebab-case, PascalCase, имя файла, имя переменной, имя компонента, имя хука]
|
|
||||||
when: "Создание файлов, переменных, компонентов, хуков — выбор имени"
|
|
||||||
---
|
|
||||||
# Именование
|
|
||||||
|
|
||||||
Этот раздел описывает соглашения об именовании в проекте. Единые правила делают код предсказуемым и упрощают навигацию по проекту.
|
|
||||||
|
|
||||||
## Базовые правила
|
|
||||||
|
|
||||||
| Что | Рекомендуется |
|
|
||||||
| ---------------- | ---------------------- |
|
|
||||||
| Папки | `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`
|
|
||||||
|
|
||||||
**Корневые компоненты модулей**
|
|
||||||
- `.business.tsx` — бизнес-модуль (`business/`)
|
|
||||||
- `.infra.tsx` — инфраструктурный модуль (`infrastructure/`)
|
|
||||||
- `.ui.tsx` — UI-компонент (`ui/`)
|
|
||||||
- `.screen.tsx` — экран (`screens/`)
|
|
||||||
- `.widget.tsx` — виджет (`widgets/`)
|
|
||||||
- `.layout.tsx` — layout (`layouts/`)
|
|
||||||
|
|
||||||
**Логика**
|
|
||||||
- `.store.ts` — стор
|
|
||||||
- `.service.ts` — сервис
|
|
||||||
|
|
||||||
**Типы и контракты**
|
|
||||||
- `.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.business.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>;
|
|
||||||
```
|
|
||||||
@@ -1,43 +0,0 @@
|
|||||||
---
|
|
||||||
title: Технологии и библиотеки
|
|
||||||
scope: basics
|
|
||||||
keywords: [стек, React, TypeScript, Next.js, Mantine, библиотека, зависимость]
|
|
||||||
when: "Выбор библиотеки или технологии, проверка допустимости зависимости"
|
|
||||||
---
|
|
||||||
# Технологии и библиотеки
|
|
||||||
|
|
||||||
Этот раздел описывает базовый стек технологий и библиотек, принятый в проекте.
|
|
||||||
|
|
||||||
## Что используем
|
|
||||||
|
|
||||||
### Стек
|
|
||||||
- `React` / `TypeScript` — основной стек для UI и приложения.
|
|
||||||
- `Next.js` — для продуктовых сайтов.
|
|
||||||
|
|
||||||
### Архитектура
|
|
||||||
- `SLM Design (Scoped Layered Module Design)` — модульная архитектура: слои, модули, направление зависимостей. Подробнее в разделе [Архитектура](/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` — шаблонизатор для создания слоёв и других файлов из шаблонов.
|
|
||||||
@@ -1,58 +0,0 @@
|
|||||||
---
|
|
||||||
title: Типизация
|
|
||||||
scope: basics
|
|
||||||
keywords: [type, interface, generic, any, unknown, enum, типизация, пропсы]
|
|
||||||
when: "Типизация кода: выбор type vs interface, работа с generic, запрет any"
|
|
||||||
---
|
|
||||||
# Типизация
|
|
||||||
|
|
||||||
Этот раздел описывает правила типизации: как типизировать компоненты, функции и работу с `any`/`unknown`.
|
|
||||||
|
|
||||||
## Общие правила
|
|
||||||
|
|
||||||
- Указывать типы для параметров компонентов, возвращаемых значений и параметров функций.
|
|
||||||
- Предпочитать `type` для описания сущностей и `interface` для расширяемых контрактов.
|
|
||||||
- Избегать `any` и `unknown` без необходимости.
|
|
||||||
- Не использовать `ts-ignore`, кроме крайних случаев с явным комментарием причины.
|
|
||||||
|
|
||||||
## Функции
|
|
||||||
|
|
||||||
- Для публичных функций указывать возвращаемый тип.
|
|
||||||
- Не полагаться на неявный вывод для важных 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;
|
|
||||||
```
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
---
|
|
||||||
title: Добавить API-запрос
|
|
||||||
---
|
|
||||||
|
|
||||||
# Добавить API-запрос
|
|
||||||
|
|
||||||
Инструкция по добавлению запроса к серверу: создание клиента, хука, обработка ответа.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/api.md — правила API-слоя: клиенты, эндпоинты, обработка ошибок
|
|
||||||
- basics/typing.md — типизация запросов и ответов
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи подход:
|
|
||||||
- Клиентские данные → SWR / хук
|
|
||||||
- Серверные данные → серверный компонент (RSC)
|
|
||||||
|
|
||||||
2. Опиши типы запроса и ответа.
|
|
||||||
|
|
||||||
3. Создай или расширь API-клиент (→ applied/api.md).
|
|
||||||
|
|
||||||
4. Создай хук для использования в компоненте (→ triggers/develop/create-hook.md).
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-hook.md — хук для запроса
|
|
||||||
- triggers/develop/create-component.md — компонент, использующий данные
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Типы запроса и ответа описаны
|
|
||||||
- [ ] Хук для использования в компоненте создан
|
|
||||||
- [ ] Обработка ошибок реализована
|
|
||||||
@@ -1,24 +0,0 @@
|
|||||||
---
|
|
||||||
title: Добавить зависимость
|
|
||||||
---
|
|
||||||
|
|
||||||
# Добавить зависимость
|
|
||||||
|
|
||||||
Инструкция по добавлению новой npm-зависимости в проект. Проверь допустимость перед установкой.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- basics/tech-stack.md — разрешённый стек, допустимые библиотеки
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Проверь, что библиотека не дублирует уже используемую (→ basics/tech-stack.md).
|
|
||||||
|
|
||||||
2. Проверь, что библиотека входит в разрешённый список или обоснуй необходимость.
|
|
||||||
|
|
||||||
3. Установи как `dependency` или `devDependency` в зависимости от назначения.
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Библиотека не дублирует уже используемую
|
|
||||||
- [ ] Библиотека входит в разрешённый список (→ basics/tech-stack.md)
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
---
|
|
||||||
title: Подключить шрифт
|
|
||||||
---
|
|
||||||
|
|
||||||
# Подключить шрифт
|
|
||||||
|
|
||||||
Инструкция по подключению и настройке шрифта в проекте.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/fonts.md — правила подключения шрифтов: форматы, загрузка, CSS-переменные
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Подготовь файлы шрифта (woff2).
|
|
||||||
|
|
||||||
2. Подключи шрифт по правилам (→ applied/fonts.md).
|
|
||||||
|
|
||||||
3. Зарегистрируй CSS-переменную для шрифта.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/style-component.md — использование шрифта в стилях
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Файл шрифта в формате woff2
|
|
||||||
- [ ] CSS-переменная для шрифта зарегистрирована
|
|
||||||
@@ -1,29 +0,0 @@
|
|||||||
---
|
|
||||||
title: Добавить иконку
|
|
||||||
---
|
|
||||||
|
|
||||||
# Добавить иконку
|
|
||||||
|
|
||||||
Инструкция по добавлению SVG-иконки в проект через спрайт-систему.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/svg-sprites.md — правила SVG-спрайтов: структура, именование, использование
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Подготовь SVG-файл: убери лишние атрибуты, оптимизируй.
|
|
||||||
|
|
||||||
2. Добавь SVG в спрайт по правилам (→ applied/svg-sprites.md).
|
|
||||||
|
|
||||||
3. Используй иконку в компоненте через компонент-обёртку.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — если нужен компонент-обёртка для иконки
|
|
||||||
- triggers/develop/style-component.md — стилизация иконки (размер, цвет)
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] SVG оптимизирован — убраны лишние атрибуты
|
|
||||||
- [ ] Иконка добавлена в спрайт по правилам (→ applied/svg-sprites.md)
|
|
||||||
@@ -1,30 +0,0 @@
|
|||||||
---
|
|
||||||
title: Добавить изображение
|
|
||||||
---
|
|
||||||
|
|
||||||
# Добавить изображение
|
|
||||||
|
|
||||||
Инструкция по добавлению и использованию растровых изображений в проекте.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/images-sprites.md — правила работы с изображениями: оптимизация, форматы, подключение
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи тип изображения:
|
|
||||||
- Статическое (логотип, декор) → `public/`
|
|
||||||
- Динамическое (контентное) → URL из API
|
|
||||||
|
|
||||||
2. Оптимизируй изображение (формат, размер, сжатие).
|
|
||||||
|
|
||||||
3. Подключи в компоненте по правилам (→ applied/images-sprites.md).
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — если нужен компонент-обёртка для изображения
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Изображение оптимизировано (формат, размер, сжатие)
|
|
||||||
- [ ] Подключено по правилам (→ applied/images-sprites.md)
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
---
|
|
||||||
title: Добавить перевод
|
|
||||||
---
|
|
||||||
|
|
||||||
# Добавить перевод
|
|
||||||
|
|
||||||
Инструкция по добавлению локализации: создание ключей перевода и подключение в компоненте.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/localization.md — правила локализации: namespace, ключи, форматирование
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи namespace для переводов (→ applied/localization.md).
|
|
||||||
|
|
||||||
2. Добавь ключи перевода в файлы локализации.
|
|
||||||
|
|
||||||
3. Подключи переводы в компоненте (→ applied/localization.md).
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — если компонент ещё не создан
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Ключи перевода добавлены в файлы локализации
|
|
||||||
- [ ] Namespace определён (→ applied/localization.md)
|
|
||||||
@@ -1,33 +0,0 @@
|
|||||||
---
|
|
||||||
title: Добавить серверные данные
|
|
||||||
---
|
|
||||||
|
|
||||||
# Добавить серверные данные
|
|
||||||
|
|
||||||
Инструкция по получению данных в серверных компонентах (RSC) Next.js.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/page-level.md — серверные компоненты в App Router
|
|
||||||
- applied/api.md — API-клиенты
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи где получать данные:
|
|
||||||
- В `page.tsx` / `layout.tsx` → серверный fetch
|
|
||||||
- В клиентском компоненте → SWR (→ triggers/develop/add-api-request.md)
|
|
||||||
|
|
||||||
2. Создай или расширь серверный API-клиент.
|
|
||||||
|
|
||||||
3. Получи данные в серверном компоненте и передай через пропсы.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/add-api-request.md — клиентские запросы (SWR)
|
|
||||||
- triggers/develop/create-page.md — серверный fetch в page.tsx
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Определён тип: серверный fetch или клиентский SWR
|
|
||||||
- [ ] Типы запроса и ответа описаны
|
|
||||||
- [ ] Данные передаются через пропсы, не через глобальное состояние
|
|
||||||
@@ -1,27 +0,0 @@
|
|||||||
---
|
|
||||||
title: Добавить видео
|
|
||||||
---
|
|
||||||
|
|
||||||
# Добавить видео
|
|
||||||
|
|
||||||
Инструкция по встраиванию видео в проект.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/video.md — правила работы с видео: форматы, плеер, оптимизация
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи тип видео:
|
|
||||||
- Локальное → `public/`
|
|
||||||
- Внешнее (YouTube, Vimeo) → embed
|
|
||||||
|
|
||||||
2. Подключи видео по правилам (→ applied/video.md).
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — если нужен компонент-обёртка для видео
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Видео подключено по правилам (→ applied/video.md)
|
|
||||||
@@ -1,31 +0,0 @@
|
|||||||
---
|
|
||||||
title: Подключить стор к компоненту
|
|
||||||
---
|
|
||||||
|
|
||||||
# Подключить стор к компоненту
|
|
||||||
|
|
||||||
Инструкция по подключению стора к React-компоненту.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/stores.md — правила сторов: подписка, селекторы
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи нужен ли стор:
|
|
||||||
- Локальное состояние → `useState` / `useReducer`
|
|
||||||
- Глобальное состояние → стор
|
|
||||||
|
|
||||||
2. Если стор не существует — создай его (→ triggers/develop/create-store.md).
|
|
||||||
|
|
||||||
3. Подключи стор в компоненте через селектор (→ applied/stores.md).
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-store.md — создание нового стора
|
|
||||||
- triggers/develop/create-hook.md — хук-обёртка над стором
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Используется селектор, а не подписка на весь стор
|
|
||||||
- [ ] Выбор локальное/глобальное состояние обоснован
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать компонент
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать компонент
|
|
||||||
|
|
||||||
Инструкция по созданию React-компонента в проекте. Определи слой, сгенерируй из шаблона, реализуй по правилам.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/components.md — правила компонентов: структура файлов, пропсы, документирование
|
|
||||||
- basics/naming.md — именование файла и экспортов
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи слой компонента по его назначению (→ basics/architecture.md):
|
|
||||||
- `ui/` — переиспользуемый UI без бизнес-логики
|
|
||||||
- `business/` — бизнес-домен с логикой и UI
|
|
||||||
- `widgets/` — составной блок, не привязанный к домену
|
|
||||||
- `screens/{name}/parts/` — локальный блок одной страницы
|
|
||||||
|
|
||||||
2. Сгенерируй модуль из шаблона (→ triggers/develop/generate-module.md).
|
|
||||||
|
|
||||||
3. Реализуй компонент по правилам (→ applied/components.md).
|
|
||||||
|
|
||||||
4. Если нужны стили — см. triggers/develop/style-component.md.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/style-component.md — стилизация компонента
|
|
||||||
- triggers/develop/add-icon.md — добавление иконки в компонент
|
|
||||||
- triggers/develop/generate-module.md — генерация из шаблона
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Компонент создан из шаблона, не вручную
|
|
||||||
- [ ] Файл и экспорт именованы по конвенции (→ basics/naming.md)
|
|
||||||
- [ ] Пропсы типизированы (→ basics/typing.md)
|
|
||||||
@@ -1,34 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать сущность
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать сущность
|
|
||||||
|
|
||||||
Инструкция по созданию бизнес-модуля на слое `business/`. Сущность — бизнес-домен с UI-представлением и моделью данных.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- basics/architecture.md — слои и зависимости
|
|
||||||
- applied/components.md — правила компонентов
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Сгенерируй модуль из шаблона `business` (→ triggers/develop/generate-module.md).
|
|
||||||
|
|
||||||
2. Определи модель данных — типы в `types/`.
|
|
||||||
|
|
||||||
3. Реализуй UI-компонент сущности.
|
|
||||||
|
|
||||||
4. Настрой публичный API — экспорт через `index.ts`.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — UI-компонент сущности
|
|
||||||
- triggers/develop/create-store.md — стор для сущности
|
|
||||||
- triggers/develop/generate-module.md — генерация из шаблона
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Модуль создан из шаблона `business`
|
|
||||||
- [ ] Модель данных определена — типы в `types/`
|
|
||||||
- [ ] Публичный API настроен — экспорт через `index.ts`
|
|
||||||
@@ -1,37 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать фичу
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать фичу
|
|
||||||
|
|
||||||
Инструкция по созданию бизнес-модуля на слое `business/`. Фича — самодостаточный блок с бизнес-логикой и UI.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- basics/architecture.md — слои и зависимости
|
|
||||||
- applied/components.md — правила компонентов
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Сгенерируй модуль из шаблона `business` (→ triggers/develop/generate-module.md).
|
|
||||||
|
|
||||||
2. Реализуй компонент фичи (→ applied/components.md).
|
|
||||||
|
|
||||||
3. Если нужен стор — создай в `stores/` (→ triggers/develop/create-store.md).
|
|
||||||
|
|
||||||
4. Если нужны хуки — создай в `hooks/` (→ triggers/develop/create-hook.md).
|
|
||||||
|
|
||||||
5. Настрой публичный API — экспорт через `index.ts`.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — компонент внутри фичи
|
|
||||||
- triggers/develop/create-store.md — стор для фичи
|
|
||||||
- triggers/develop/create-hook.md — хук для фичи
|
|
||||||
- triggers/develop/generate-module.md — генерация из шаблона
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Модуль создан из шаблона `business`
|
|
||||||
- [ ] Публичный API настроен — экспорт через `index.ts`
|
|
||||||
- [ ] Cross-domain зависимости реализованы через фабрику (→ basics/architecture.md)
|
|
||||||
@@ -1,36 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать хук
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать хук
|
|
||||||
|
|
||||||
Инструкция по созданию кастомного React-хука. Определи где он живёт, реализуй по правилам.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/hooks.md — правила хуков
|
|
||||||
- basics/naming.md — именование (префикс `use`)
|
|
||||||
- basics/typing.md — типизация параметров и возврата
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи область хука:
|
|
||||||
- Утилитарный (не привязан к бизнес-логике) → `shared/hooks/`
|
|
||||||
- Привязан к фиче/сущности → `model/` внутри модуля
|
|
||||||
|
|
||||||
2. Создай файл с именем `use-{name}.ts`.
|
|
||||||
|
|
||||||
3. Реализуй хук по правилам (→ applied/hooks.md).
|
|
||||||
|
|
||||||
4. Экспортируй через публичный API модуля.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — если хук используется в новом компоненте
|
|
||||||
- triggers/develop/connect-store.md — если хук подключает стор
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Имя начинается с `use` (→ basics/naming.md)
|
|
||||||
- [ ] Параметры и возвращаемое значение типизированы
|
|
||||||
- [ ] Хук экспортирован через публичный API модуля
|
|
||||||
@@ -1,34 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать layout
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать layout
|
|
||||||
|
|
||||||
Инструкция по созданию layout.tsx в Next.js App Router.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/page-level.md — правила layout.tsx: провайдеры, metadata, вёрстка
|
|
||||||
- applied/project-structure.md — структура `src/app/`
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи уровень layout:
|
|
||||||
- Корневой (`src/app/layout.tsx`) — провайдеры, глобальные стили, metadata
|
|
||||||
- Вложенный (`src/app/{route}/layout.tsx`) — layout для группы страниц
|
|
||||||
|
|
||||||
2. Создай `layout.tsx` в нужном маршруте.
|
|
||||||
|
|
||||||
3. Вёрстку layout-обёрток вынеси в слой `layouts/` (→ applied/page-level.md).
|
|
||||||
|
|
||||||
4. Layout содержит только провайдеры и вызов layout-компонента — не вёрстку.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-page.md — страницы внутри layout
|
|
||||||
- triggers/develop/create-component.md — layout-компонент в `layouts/`
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Вёрстка вынесена в layout-компонент в `layouts/`
|
|
||||||
- [ ] layout.tsx содержит только провайдеры и вызов layout-компонента
|
|
||||||
@@ -1,36 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать страницу
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать страницу
|
|
||||||
|
|
||||||
Инструкция по добавлению нового route в Next.js проект. Страница — это экран + page.tsx.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/page-level.md — правила файлов роутинга: page.tsx, layout.tsx, metadata
|
|
||||||
- applied/project-structure.md — где располагаются файлы
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Сгенерируй экран из шаблона `screen` в `src/screens/` (→ triggers/develop/generate-module.md).
|
|
||||||
|
|
||||||
2. Заполни экран логикой и стилями.
|
|
||||||
|
|
||||||
3. Создай `page.tsx` в нужном маршруте `src/app/`.
|
|
||||||
- page.tsx тонкий: только `metadata` и рендер экрана
|
|
||||||
- Никакой логики, стилей и хуков в page.tsx
|
|
||||||
|
|
||||||
4. Добавь `metadata` с `title` (→ applied/page-level.md).
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/generate-module.md — генерация экрана из шаблона
|
|
||||||
- triggers/develop/create-layout.md — если нужен новый layout для маршрута
|
|
||||||
- triggers/develop/create-component.md — компоненты внутри экрана
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Экран создан из шаблона `screen` в `src/screens/`
|
|
||||||
- [ ] page.tsx тонкий — только metadata и рендер экрана
|
|
||||||
- [ ] metadata содержит title и description
|
|
||||||
@@ -1,52 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать проект
|
|
||||||
scope: applied
|
|
||||||
keywords: [создать проект, новый проект, tiged, шаблон проекта, init]
|
|
||||||
when: "Создание нового Next.js проекта из шаблона"
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать проект
|
|
||||||
|
|
||||||
Инструкция по созданию нового Next.js проекта из готового шаблона. Проект готов к разработке сразу после установки зависимостей.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- basics/getting-started.md — знакомство со стеком и особенностями проекта
|
|
||||||
- applied/project-structure.md — структура папок и файлов
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Создай проект из шаблона:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npx tiged git@gromlab.ru:templates/nextjs.git my-app
|
|
||||||
cd my-app
|
|
||||||
npm install
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Ознакомься со структурой проекта (→ applied/project-structure.md).
|
|
||||||
|
|
||||||
3. Настрой VS Code (→ triggers/develop/setup-vscode.md).
|
|
||||||
|
|
||||||
## Что входит в шаблон
|
|
||||||
|
|
||||||
- Next.js + TypeScript (App Router)
|
|
||||||
- Mantine UI + PostCSS Modules
|
|
||||||
- Biome (линтинг и форматирование)
|
|
||||||
- Zustand, SWR
|
|
||||||
- Структура SLM Design (`screens/`, `layouts/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`)
|
|
||||||
- Шаблоны генерации (`.templates/`)
|
|
||||||
- Конфигурация VS Code (`.vscode/`)
|
|
||||||
- CSS-токены (цвета, отступы, радиусы, медиа)
|
|
||||||
- Open Graph метаданные
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/setup-vscode.md — настройка редактора
|
|
||||||
- triggers/develop/create-page.md — добавление первой страницы
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Проект создан из шаблона через `npx tiged`
|
|
||||||
- [ ] Зависимости установлены
|
|
||||||
- [ ] VS Code настроен (→ triggers/develop/setup-vscode.md)
|
|
||||||
@@ -1,36 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать стор
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать стор
|
|
||||||
|
|
||||||
Инструкция по созданию стора для управления состоянием. Определи область, сгенерируй из шаблона.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/stores.md — правила сторов
|
|
||||||
- basics/naming.md — именование
|
|
||||||
- basics/typing.md — типизация состояния и экшенов
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи область стора:
|
|
||||||
- Глобальный → `shared/model/`
|
|
||||||
- Привязан к фиче/сущности → `model/` внутри модуля
|
|
||||||
|
|
||||||
2. Сгенерируй из шаблона `store` (→ triggers/develop/generate-module.md).
|
|
||||||
|
|
||||||
3. Реализуй стор по правилам (→ applied/stores.md).
|
|
||||||
|
|
||||||
4. Экспортируй через публичный API модуля.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/connect-store.md — подключение стора к компоненту
|
|
||||||
- triggers/develop/generate-module.md — генерация из шаблона
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Стор создан из шаблона `store`
|
|
||||||
- [ ] Состояние и экшены типизированы
|
|
||||||
- [ ] Стор экспортирован через публичный API модуля
|
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
---
|
|
||||||
title: Создать виджет
|
|
||||||
---
|
|
||||||
|
|
||||||
# Создать виджет
|
|
||||||
|
|
||||||
Инструкция по созданию модуля на слое `widgets/`. Виджет — композиция фичей и сущностей.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- basics/architecture.md — слои и зависимости
|
|
||||||
- applied/components.md — правила компонентов
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Сгенерируй модуль из шаблона `widget` (→ triggers/develop/generate-module.md).
|
|
||||||
|
|
||||||
2. Скомпонуй виджет из существующих фичей и сущностей.
|
|
||||||
|
|
||||||
3. Настрой публичный API — экспорт через `index.ts`.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-feature.md — если нужна новая фича для виджета
|
|
||||||
- triggers/develop/create-component.md — UI-компоненты внутри виджета
|
|
||||||
- triggers/develop/generate-module.md — генерация из шаблона
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Виджет создан из шаблона `widget`
|
|
||||||
- [ ] Композиция из существующих фичей/сущностей, не дублирует логику
|
|
||||||
- [ ] Публичный API настроен — экспорт через `index.ts`
|
|
||||||
@@ -1,36 +0,0 @@
|
|||||||
---
|
|
||||||
title: Сгенерировать модуль из шаблона
|
|
||||||
---
|
|
||||||
|
|
||||||
# Сгенерировать модуль из шаблона
|
|
||||||
|
|
||||||
Инструкция по генерации модуля из шаблонов `.templates/`. Ручное создание файловой структуры запрещено.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/templates-generation.md — шаблоны, синтаксис, инструменты генерации
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи тип модуля и шаблон (→ applied/templates-generation.md):
|
|
||||||
- Компонент → `component`
|
|
||||||
- Бизнес-модуль → `business`
|
|
||||||
- Виджет → `widget`
|
|
||||||
- Layout → `layout`
|
|
||||||
- Экран → `screen`
|
|
||||||
- Стор → `store`
|
|
||||||
|
|
||||||
2. Запусти генерацию (→ applied/templates-generation.md).
|
|
||||||
|
|
||||||
3. Если подходящего шаблона нет — сначала создай шаблон, затем генерируй.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — после генерации компонента
|
|
||||||
- triggers/develop/create-feature.md — после генерации бизнес-модуля
|
|
||||||
- triggers/develop/create-store.md — после генерации стора
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Модуль создан из шаблона, не вручную
|
|
||||||
- [ ] Выбран правильный шаблон для типа модуля (→ applied/templates-generation.md)
|
|
||||||
@@ -1,24 +0,0 @@
|
|||||||
---
|
|
||||||
title: Настроить VS Code
|
|
||||||
---
|
|
||||||
|
|
||||||
# Настроить VS Code
|
|
||||||
|
|
||||||
Инструкция по настройке VS Code для работы с проектом.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/vscode.md — настройки, расширения, сниппеты
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Установи рекомендованные расширения (→ applied/vscode.md).
|
|
||||||
|
|
||||||
2. Проверь настройки `.vscode/settings.json`.
|
|
||||||
|
|
||||||
3. Настрой сниппеты при необходимости.
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Рекомендованные расширения установлены
|
|
||||||
- [ ] Настройки `.vscode/settings.json` проверены
|
|
||||||
@@ -1,35 +0,0 @@
|
|||||||
---
|
|
||||||
title: Стилизовать компонент
|
|
||||||
---
|
|
||||||
|
|
||||||
# Стилизовать компонент
|
|
||||||
|
|
||||||
Инструкция по выбору подхода к стилизации и написанию стилей для компонента.
|
|
||||||
|
|
||||||
## Прочитай перед началом
|
|
||||||
|
|
||||||
- applied/styles.md — правила CSS: PostCSS Modules, токены, медиа-запросы
|
|
||||||
|
|
||||||
## Шаги
|
|
||||||
|
|
||||||
1. Определи подход (→ applied/styles.md):
|
|
||||||
- Mantine-компонент → используй пропсы Mantine, не пиши CSS
|
|
||||||
- CSS-токены достаточно → используй токены
|
|
||||||
- Нужна кастомная стилизация → PostCSS Modules
|
|
||||||
|
|
||||||
2. Создай файл стилей `{component-name}.module.css` рядом с компонентом.
|
|
||||||
|
|
||||||
3. Напиши стили по правилам (→ applied/styles.md).
|
|
||||||
|
|
||||||
4. Подключи стили в компоненте через `cl()`.
|
|
||||||
|
|
||||||
## Смежные триггеры
|
|
||||||
|
|
||||||
- triggers/develop/create-component.md — если компонент ещё не создан
|
|
||||||
- triggers/develop/add-icon.md — если нужна иконка в компоненте
|
|
||||||
|
|
||||||
## Проверь себя
|
|
||||||
|
|
||||||
- [ ] Приоритет стилизации соблюдён: Mantine → токены → PostCSS Modules
|
|
||||||
- [ ] Нет инлайн-стилей и магических значений
|
|
||||||
- [ ] Файл стилей именован `{component-name}.module.css`
|
|
||||||
Reference in New Issue
Block a user