nextjs-style-guide/README.md

# NextJS Style Guide

Rules and standards for NextJS and TypeScript development: architecture, typing, styles, components, API, and infrastructure.

## Documentation Structure

### Processes

**What to do** in a specific situation — step-by-step instructions.

| Section | Answers the question |
|---------|---------------------|
| Getting Started | What tools to install before starting development? |
| Creating an App | How to create a new project, where to get a template? |
| Creating Pages | How to add a page: routing and screen? |
| Creating Components | How to generate components using templates? |
| Styling | What to use: Mantine, tokens, or PostCSS? |
| Data Fetching | How to fetch data: SWR, codegen, sockets? |
| State Management | When and how to create a store (Zustand)? |
| Localization | How to add translations and work with i18next? |

### Basic Rules

**What the code should look like** — standards not tied to a specific technology.

| Section | Answers the question |
|---------|---------------------|
| Tech Stack | What stack do we use? |
| Architecture | How are FSD layers, dependencies, and public API structured? |
| Code Style | How to format code: indentation, quotes, imports, early return? |
| Naming | How to name files, variables, components, hooks? |
| Documentation | How to write JSDoc: what to document and what not? |
| Typing | How to type: type vs interface, any/unknown? |

### Applied Sections

**How a specific area works** — rules, structure, and code examples for specific technologies and tools.

| Section | Answers the question |
|---------|---------------------|
| Project Structure | How are folders and files organized by FSD? |
| Components | How is a component structured: files, props, clsx? |
| Page-level Components | How to define layout, page, loading, error, not-found? |
| Templates & Code Generation | How do templates work: syntax, variables, modifiers? |
| Styles | How to write CSS: PostCSS Modules, nesting, media, tokens? |
| Images | _(not filled)_ |
| SVG Sprites | _(not filled)_ |
| Video | _(not filled)_ |
| API | _(not filled)_ |
| Stores | _(not filled)_ |
| Hooks | _(not filled)_ |
| Fonts | _(not filled)_ |
| Localization | _(not filled)_ |

## For Assistants

Documentation map with links to all sections ([llmstxt.org](https://llmstxt.org) format):
https://gromlab.ru/docs/nextjs-style-guide/raw/branch/main/generated/en/llms.txt
sync 2026-03-28 21:15:15 +03:00			`# NextJS Style Guide`
sync 2026-01-29 16:00:19 +03:00
sync 2026-03-28 21:15:15 +03:00			`Rules and standards for NextJS and TypeScript development: architecture, typing, styles, components, API, and infrastructure.`
sync 2026-01-29 16:00:19 +03:00
sync 2026-03-28 21:15:15 +03:00			`## Documentation Structure`
sync 2026-01-29 16:00:19 +03:00
sync 2026-03-28 21:15:15 +03:00			`### Processes`
sync 2026-01-29 16:00:19 +03:00
sync 2026-03-28 21:15:15 +03:00			`What to do in a specific situation — step-by-step instructions.`
sync 2026-01-29 16:00:19 +03:00
sync 2026-03-28 21:15:15 +03:00			`\| Section \| Answers the question \|`
			`\|---------\|---------------------\|`
			`\| Getting Started \| What tools to install before starting development? \|`
			`\| Creating an App \| How to create a new project, where to get a template? \|`
			`\| Creating Pages \| How to add a page: routing and screen? \|`
			`\| Creating Components \| How to generate components using templates? \|`
			`\| Styling \| What to use: Mantine, tokens, or PostCSS? \|`
			`\| Data Fetching \| How to fetch data: SWR, codegen, sockets? \|`
			`\| State Management \| When and how to create a store (Zustand)? \|`
			`\| Localization \| How to add translations and work with i18next? \|`

			`### Basic Rules`

			`What the code should look like — standards not tied to a specific technology.`

			`\| Section \| Answers the question \|`
			`\|---------\|---------------------\|`
			`\| Tech Stack \| What stack do we use? \|`
			`\| Architecture \| How are FSD layers, dependencies, and public API structured? \|`
			`\| Code Style \| How to format code: indentation, quotes, imports, early return? \|`
			`\| Naming \| How to name files, variables, components, hooks? \|`
			`\| Documentation \| How to write JSDoc: what to document and what not? \|`
docs: отказаться от FC и interface в пропсах компонентов - переписана типизация: type вместо interface, убран FC - введена система типов: Params + RootAttrs + Props - добавлены обоснования: почему type, почему не FC, почему types/ - обновлены примеры в components, page-level, templates, documentation - убраны упоминания FC из таблиц index.md и README - перегенерированы RULES.md 2026-04-02 16:01:29 +03:00			`\| Typing \| How to type: type vs interface, any/unknown? \|`
sync 2026-03-28 21:15:15 +03:00
			`### Applied Sections`

			`How a specific area works — rules, structure, and code examples for specific technologies and tools.`

			`\| Section \| Answers the question \|`
			`\|---------\|---------------------\|`
			`\| Project Structure \| How are folders and files organized by FSD? \|`
docs: отказаться от FC и interface в пропсах компонентов - переписана типизация: type вместо interface, убран FC - введена система типов: Params + RootAttrs + Props - добавлены обоснования: почему type, почему не FC, почему types/ - обновлены примеры в components, page-level, templates, documentation - убраны упоминания FC из таблиц index.md и README - перегенерированы RULES.md 2026-04-02 16:01:29 +03:00			`\| Components \| How is a component structured: files, props, clsx? \|`
docs: рефакторинг документации — workflow, прикладные разделы, генерация RULES.md - Переработан раздел Workflow: заголовки, описания, порядок разделов - Добавлены новые разделы: Генерация кода (workflow), Настройка VS Code (applied) - Убран суффикс .ui.tsx из документации и примеров - Переработан раздел Структура проекта — только Next.js, без React SPA - Приоритет стилизации перенесён из applied/styles в workflow/styling - Убрано дублирование инструментов генерации — единая точка в applied/templates-generation - Переписан concat-md.js: без внешних зависимостей, мета-якоря для навигации в RULES.md - Удалена зависимость concat-md - Обновлена главная страница: названия разделов, URL на RULES.md - Добавлен AGENTS.md с правилами для агентов 2026-03-29 11:43:23 +03:00			`\| Page-level Components \| How to define layout, page, loading, error, not-found? \|`
sync 2026-03-28 21:15:15 +03:00			`\| Templates & Code Generation \| How do templates work: syntax, variables, modifiers? \|`
			`\| Styles \| How to write CSS: PostCSS Modules, nesting, media, tokens? \|`
			`\| Images \| _(not filled)_ \|`
			`\| SVG Sprites \| _(not filled)_ \|`
			`\| Video \| _(not filled)_ \|`
			`\| API \| _(not filled)_ \|`
			`\| Stores \| _(not filled)_ \|`
			`\| Hooks \| _(not filled)_ \|`
			`\| Fonts \| _(not filled)_ \|`
			`\| Localization \| _(not filled)_ \|`

			`## For Assistants`

feat: генерация llms.txt, лендинг с выбором языка и ZIP-архивов - удалён concat-md.js: вместо единого RULES.md теперь llms.txt - добавлен generate-llms.ts: собирает llms.txt из sidebar config, копирует .md-файлы для отдачи LLM и упаковывает ZIP-архивы по локалям - добавлен корневой /llms.txt как роутер на /ru/llms.txt и /en/llms.txt - добавлен манифест /manifest.json со ссылками и версией сборки - добавлен лендинг docs/index.md (layout: false) с автоопределением языка, переключателями языка и темы - английская локаль временно заблокирована: карточки как заглушки, ссылка на /en/ в роутере без href - добавлены поля llmsBlockquote и llmsContext в локали для технодокументационного описания в llms.txt - разделены VitePress-локали: root (только лендинг), ru (/ru/), en (/en/) - добавлен srcExclude: ['public/'] чтобы VitePress не рендерил сгенерированные .md как страницы - добавлен Vite-плагин для отдачи .txt и .md с charset=utf-8 - добавлена секция в Caddyfile для текстовых файлов - BUILD_VERSION пробрасывается из Gitea CI через docker --build-arg и подставляется в лендинг через Vite define - Dockerfile: установка zip, npm run llms перед npm run build - обновлены внутренние ссылки в docs/ru//*.md на префикс /ru/ - обновлены AGENTS.md и CONTRIBUTING.md под новый процесс - README/README_RU генерируются из docs/{lang}/index.md, остаются в репо 2026-04-25 18:06:27 +03:00			`Documentation map with links to all sections ([llmstxt.org](https://llmstxt.org) format):`
			`https://gromlab.ru/docs/nextjs-style-guide/raw/branch/main/generated/en/llms.txt`