docs: добавить стайлгайд nextjs-style-guide в репозиторий
- Добавлена документация SLM-архитектуры, базовых правил и прикладных разделов - Добавлены разделы: стили, SVG-спрайты, шаблоны генерации, PostCSS, REST, Realtime - Удалены устаревшие файлы (спрайты, скрипты, стили из app/)
This commit is contained in:
51
ai/nextjs-style-guide/creating-project/from-template.md
Normal file
51
ai/nextjs-style-guide/creating-project/from-template.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Создание проекта из шаблона
|
||||
description: Создание нового проекта на основе готового шаблона.
|
||||
keywords: [создать проект из шаблона, шаблон, template, tiged, degit, клонировать шаблон, эталонный шаблон, быстрый старт, scaffold, новый проект]
|
||||
---
|
||||
|
||||
# Создание проекта из шаблона
|
||||
|
||||
Создание нового проекта на основе готового шаблона.
|
||||
|
||||
## Что внутри
|
||||
|
||||
Шаблон — готовый скелет проекта с применёнными правилами стайлгайда:
|
||||
|
||||
- **Стек:** Next.js (App Router), TypeScript, React.
|
||||
- **Архитектура:** структура папок по SLM, алиасы импортов.
|
||||
- **Качество кода:** Biome (линтер и форматер), настройки VS Code.
|
||||
- **Стили:** PostCSS Modules с плагинами, токены, медиа-брейкпоинты.
|
||||
- **Ассеты:** генерация SVG-спрайтов.
|
||||
- **Кодогенерация:** шаблоны для страниц, компонентов, хуков, сторов.
|
||||
в
|
||||
## Установка
|
||||
|
||||
1. Склонировать шаблон в родительском каталоге будущего проекта:
|
||||
|
||||
```bash
|
||||
npx tiged git@gromlab.ru:templates/nextjs.git my-app
|
||||
```
|
||||
|
||||
`tiged` копирует снимок репозитория без истории git. Имя каталога (`my-app`) заменяется на нужное.
|
||||
|
||||
2. Установить зависимости:
|
||||
|
||||
```bash
|
||||
cd my-app
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Проверить сборку:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Сборка должна завершиться без ошибок.
|
||||
|
||||
## Правила
|
||||
|
||||
- **Шаблон — источник истины.** Не добавлять, не удалять и не переименовывать файлы шаблона «для приведения к канону»: шаблон уже канонический. Любое несоответствие — баг шаблона, а не проекта.
|
||||
- **Менеджер пакетов — npm.** Отклонение (pnpm, yarn, bun) — только по явному решению с пониманием, что стайлгайд этого не предусматривает.
|
||||
- **Не инициализировать git заново** автоматически. `tiged` намеренно не создаёт `.git/` — решение о репозитории принимает разработчик.
|
||||
90
ai/nextjs-style-guide/creating-project/manual.md
Normal file
90
ai/nextjs-style-guide/creating-project/manual.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Создание проекта вручную
|
||||
description: Поэтапное создание нового проекта без использования шаблона.
|
||||
keywords: [создать проект, новый проект, с нуля, init, initialize, scaffold, create-next-app, начать проект, поднять проект, эталонный проект, ручная установка]
|
||||
---
|
||||
|
||||
# Создание проекта вручную
|
||||
|
||||
Поэтапное создание нового проекта без использования шаблона.
|
||||
|
||||
## Состав эталонного проекта
|
||||
|
||||
| Компонент | Роль | Раздел |
|
||||
|-----------|------|--------|
|
||||
| Next.js | Фреймворк (роутинг, сборка, SSR) | [Next.js](./nextjs.md) |
|
||||
| Алиасы | Импорты по слоям SLM | [Алиасы](../applied/aliases.md) |
|
||||
| Biome | Линтер и форматтер (замена ESLint + Prettier) | [Biome](../applied/biome.md) |
|
||||
| Стили | Глобальные токены и breakpoints | [Стили](../applied/styles/styles-setup.md) |
|
||||
| PostCSS | CSS-процессор для custom-media и вложенности | [PostCSS](../applied/postcss.md) |
|
||||
| SVG-спрайты | Иконки через `<SvgSprite/>`, управление цветом | [SVG-спрайты](../applied/svg-sprites/svg-sprites-setup.md) |
|
||||
| VS Code | Настройки редактора и расширения | [VS Code](../applied/vscode.md) |
|
||||
| Шаблоны генерации | `.templates/` для `@gromlab/create` | [Шаблоны генерации](../applied/templates/templates-setup.md) |
|
||||
|
||||
Убрать компонент из состава — значит согласованно отказаться от части стайлгайда. Частичные проекты возможны (только Next.js, Next.js + стили и т.п.), но не являются эталоном.
|
||||
|
||||
## Канон раскладки
|
||||
|
||||
В `src/` допустимы только слои SLM: `app/`, `layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`, `shared/`. Любая другая папка в `src/` — нарушение канона ([Структура проекта](../applied/project-structure.md), [Архитектура](../basics/architecture/index.md)).
|
||||
|
||||
В частности: `src/app/` содержит только файлы роутинга Next.js и инициализации, без каталогов `styles/`, `assets/`, `components/`.
|
||||
|
||||
## Порядок установки
|
||||
|
||||
Подсистемы ставятся в фиксированном порядке — он отражает зависимости между шагами.
|
||||
|
||||
### 1. Next.js
|
||||
|
||||
Скелет фреймворка — обязательный первый шаг, остальное опирается на него.
|
||||
|
||||
См. [Next.js](./nextjs.md). После выполнения проверки этого раздела `npm run build` должен проходить.
|
||||
|
||||
### 2. Алиасы
|
||||
|
||||
Заменить дефолтный `"@/*"` в `tsconfig.json` на канонический список из восьми слой-префиксов.
|
||||
|
||||
См. [Алиасы](../applied/aliases.md).
|
||||
|
||||
### 3. Biome
|
||||
|
||||
Линтер и форматтер. Подключается **до** написания кода, иначе в проекте копятся несогласованные правки.
|
||||
|
||||
См. [Biome](../applied/biome.md).
|
||||
|
||||
### 4. Стили (базовая инфраструктура)
|
||||
|
||||
Файлы `variables.css`, `media.css`, `global.css` в `src/shared/styles/` и подключение `global.css` в `src/app/layout.tsx`. CSS-процессор на этом шаге не ставится.
|
||||
|
||||
См. [Стили](../applied/styles/styles-setup.md).
|
||||
|
||||
### 5. PostCSS
|
||||
|
||||
CSS-процессор поверх базовых стилей: `@custom-media`, вложенность, autoprefixer. Ставится **только после шага 4** — опирается на `src/shared/styles/media.css`.
|
||||
|
||||
См. [PostCSS](../applied/postcss.md).
|
||||
|
||||
### 6. SVG-спрайты
|
||||
|
||||
Пакет `@gromlab/svg-sprites`, генерация спрайт-файла и React-компонента `<SvgSprite/>`.
|
||||
|
||||
См. [SVG-спрайты](../applied/svg-sprites/svg-sprites-setup.md).
|
||||
|
||||
### 7. VS Code
|
||||
|
||||
Расширения и настройки редактора. Опирается на установленный Biome (форматирование при сохранении) и PostCSS (ассоциация `*.css`).
|
||||
|
||||
См. [VS Code](../applied/vscode.md).
|
||||
|
||||
### 8. Шаблоны генерации
|
||||
|
||||
Папка `.templates/` для генератора модулей `@gromlab/create`.
|
||||
|
||||
См. [Шаблоны генерации](../applied/templates/templates-setup.md).
|
||||
|
||||
## Правила
|
||||
|
||||
- **Порядок шагов фиксирован.** Перестановка ломает зависимости (PostCSS требует базовых стилей, VS Code — установленного Biome).
|
||||
- **Между шагами обязательна проверка** из соответствующего раздела. Не переходить дальше, пока чеклист текущего шага не пройден.
|
||||
- **Слои `src/`** (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`) не создавать авансом. Появляются по мере первого модуля. Исключения — `src/app/` (создаётся `create-next-app`), `src/shared/styles/` (шаг 1) и `src/shared/sprites/icons/` (шаг 6).
|
||||
- **Посторонние каталоги в `src/`** (`assets/`, `utils/`, `lib/`, `components/` и т.п.) — запрещены.
|
||||
- **Подмножество шагов допустимо.** Можно ставить только Next.js и часть инструментов; полный набор — это эталон, а не обязательство.
|
||||
112
ai/nextjs-style-guide/creating-project/nextjs.md
Normal file
112
ai/nextjs-style-guide/creating-project/nextjs.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Чистая установка Next.js
|
||||
description: "Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку."
|
||||
keywords: [next.js, create-next-app, npx, установка, инициализация, фреймворк, скаффолдинг, app router, typescript]
|
||||
---
|
||||
|
||||
# Чистая установка Next.js
|
||||
|
||||
Установка Next.js без лишнего шаблона — голый каркас под дальнейшую сборку.
|
||||
|
||||
## Требования
|
||||
|
||||
- Node.js 18.18+ (рекомендуется LTS 20+).
|
||||
- npm 10+.
|
||||
- Рабочая папка пуста, либо для установки выбрана подпапка (`create-next-app@16+` отказывается ставиться в непустую директорию).
|
||||
|
||||
## Установка
|
||||
|
||||
### 1. Инициализация через `create-next-app`
|
||||
|
||||
Флаги зафиксированы и не согласовываются — это канон стайлгайда:
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest my-app \
|
||||
--typescript \
|
||||
--app \
|
||||
--src-dir \
|
||||
--import-alias "@/*" \
|
||||
--no-eslint \
|
||||
--no-tailwind \
|
||||
--use-npm
|
||||
```
|
||||
|
||||
| Флаг | Значение | Почему так |
|
||||
|------|----------|------------|
|
||||
| `--typescript` | TS включён | Стайлгайд требует TypeScript ([Типизация](../basics/typing.md)) |
|
||||
| `--app` | App Router | Pages Router не используется |
|
||||
| `--src-dir` | Код в `src/` | Архитектура SLM требует `src/` ([Структура проекта](../applied/project-structure.md)) |
|
||||
| `--import-alias "@/*"` | Placeholder | Требуется флагом; после установки `paths` полностью переписывается на слой-префиксы (см. [Алиасы](../applied/aliases.md)) |
|
||||
| `--no-eslint` | ESLint не ставится | Линтер и форматтер — Biome ([Biome](../applied/biome.md)) |
|
||||
| `--no-tailwind` | Tailwind не ставится | Стилизация — PostCSS Modules ([Стили](../applied/styles/styles-usage.md)) |
|
||||
| `--use-npm` | Пакетный менеджер — npm | Единый инструмент в проектах |
|
||||
|
||||
### 2. Очистить дефолтный шаблон
|
||||
|
||||
`create-next-app` генерирует демо-страницу со стилями и ассетами, а Next.js 16+ дополнительно кладёт в корень собственные `AGENTS.md` и `CLAUDE.md` — всё это удаляется.
|
||||
|
||||
```bash
|
||||
rm src/app/page.module.css
|
||||
rm src/app/globals.css
|
||||
rm public/next.svg public/vercel.svg public/file.svg public/globe.svg public/window.svg
|
||||
rm -f AGENTS.md CLAUDE.md
|
||||
```
|
||||
|
||||
Заменить `src/app/page.tsx` на минимальный:
|
||||
|
||||
```tsx
|
||||
// src/app/page.tsx
|
||||
export default function HomePage() {
|
||||
return <h1>Home</h1>
|
||||
}
|
||||
```
|
||||
|
||||
Очистить `src/app/layout.tsx` от импорта шрифтов и `globals.css`:
|
||||
|
||||
```tsx
|
||||
// src/app/layout.tsx
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'App',
|
||||
description: '',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<html lang="ru">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Создать папку `src/shared/styles/`
|
||||
|
||||
Глобальные стили в SLM-архитектуре живут в слое `shared`, а не в `src/app/` ([Структура проекта](../applied/project-structure.md)).
|
||||
|
||||
```bash
|
||||
mkdir -p src/shared/styles
|
||||
```
|
||||
|
||||
Остальные слои (`layouts/`, `screens/`, `widgets/`, `business/`, `infrastructure/`, `ui/`) заводятся при появлении первого модуля в них. `src/shared/styles/` — единственный подкаталог `shared/`, который заводится сразу: без него не настроить стили на следующих шагах.
|
||||
|
||||
## Правила
|
||||
|
||||
- **Конфликт с непустой директорией** — не удалять файлы пользователя автоматически. Ставить в подпапку или временно перенести посторонние файлы.
|
||||
- **Отклонение от канонических флагов** (pnpm, Tailwind, ESLint и т.п.) — только осознанное, с пониманием, что стайлгайд этого не предусматривает.
|
||||
- **Слои `src/`** не создавать авансом — появляются при первом модуле. Алиасы прописываются сразу на все восемь слоёв (см. [Алиасы](../applied/aliases.md)).
|
||||
- **`AGENTS.md` от Next.js** удаляется в шаге 2. Повторно не создаётся.
|
||||
- **Biome, стили, PostCSS, SVG-спрайты, VS Code** — отдельные шаги установки, не в этом разделе.
|
||||
|
||||
## Проверка установки
|
||||
|
||||
- В корне проекта: `next.config.ts`, `tsconfig.json`, `package.json`.
|
||||
- В `package.json`: Next.js установлен, нет `eslint`, `tailwindcss`.
|
||||
- В `src/app/` присутствуют минимальные `page.tsx` и `layout.tsx`. `globals.css`, `page.module.css` отсутствуют. Каталогов `styles/`, `assets/`, `providers/`, `components/` в `src/app/` нет.
|
||||
- Папка `src/shared/styles/` создана (пустая).
|
||||
- В `src/` из слоёв SLM присутствуют только `app/` и `shared/` (с `styles/`). Посторонних каталогов нет.
|
||||
- В `public/` удалены `next.svg`, `vercel.svg`, `file.svg`, `globe.svg`, `window.svg`.
|
||||
- В корне проекта нет `AGENTS.md` и `CLAUDE.md` от Next.js.
|
||||
- `npm run build` завершается успешно.
|
||||
- Пакетный менеджер — npm (нет `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`).
|
||||
Reference in New Issue
Block a user