nextjs-style-guide/generated/en/RULES.md

<!-- /index -->
# 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, FC? |

### 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, FC? |
| 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

Full documentation in a single MD file: https://gromlab.ru/docs/frontend-style-guide/raw/branch/main/generated/en/RULES.md

<!-- /workflow/getting-started -->
## Getting Started

Setting up the environment and installing tools before starting development.

<!-- /workflow/creating-app -->
## Creating an App

How to create a new application: choosing a project template and initialization.

<!-- /workflow/creating-pages -->
## Creating Pages

Page creation pattern: routing (page.tsx) and screen.

<!-- /workflow/creating-components -->
## Creating Components

Generating components using templates, working with child components.

<!-- /workflow/styling -->
## Styling

Styling tools priority and rules for their application.

<!-- /workflow/data-fetching -->
## Data Fetching

How to fetch data: SWR, API client codegen, sockets.

<!-- /workflow/state-management -->
## State Management

When and how to create a store (Zustand), what to store locally vs globally.

<!-- /workflow/localization -->
## Localization

How to add translations and work with i18next.

<!-- /basics/tech-stack -->
## Tech Stack

Base technology stack and libraries used in projects.

<!-- /basics/architecture -->
## Architecture

Architecture based on FSD (Feature-Sliced Design) and strict module boundaries.

<!-- /basics/code-style -->
## Code Style

Unified code formatting rules: indentation, line breaks, quotes, import order, and readability.

<!-- /basics/naming -->
## Naming

Naming should be predictable, concise, and reflect the meaning of the entity.

<!-- /basics/documentation -->
## Documentation

Documentation should help understand the purpose of an entity, not duplicate its types or obvious details.

<!-- /basics/typing -->
## Typing

Typing is required for all public interfaces, functions, and components.

<!-- /applied/project-structure -->
## Project Structure

Base project structure and principles of module organization at folder and file level.

<!-- /applied/components -->
## Components

Rules for creating UI components across all FSD layers.

<!-- /applied/page-level -->
## Page-level Components

Next.js App Router special files used by the framework by convention: `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`, `template.tsx`.

<!-- /applied/templates-generation -->
## Templates & Code Generation

Template tools, syntax, and examples for code generation.

<!-- /applied/styles -->
## Styles

CSS writing rules: PostCSS Modules, nesting, media queries, variables, formatting.

<!-- /applied/images-sprites -->
## Images

<!-- /applied/svg-sprites -->
## SVG Sprites

<!-- /applied/video -->
## Video

<!-- /applied/api -->
## API

<!-- /applied/stores -->
## Stores

<!-- /applied/hooks -->
## Hooks

<!-- /applied/fonts -->
## Fonts

<!-- /applied/localization -->
## Localization