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

<a name="indexmd"></a>

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


<a name="workflowgetting-startedmd"></a>

# Getting Started

Setting up the environment and installing tools before starting development.


<a name="workflowcreating-appmd"></a>

# Creating an App

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


<a name="workflowcreating-pagesmd"></a>

# Creating Pages

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


<a name="workflowcreating-componentsmd"></a>

# Creating Components

Generating components using templates, working with child components.


<a name="workflowstylingmd"></a>

# Styling

Styling tools priority and rules for their application.


<a name="workflowdata-fetchingmd"></a>

# Data Fetching

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


<a name="workflowstate-managementmd"></a>

# State Management

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


<a name="workflowlocalizationmd"></a>

# Localization

How to add translations and work with i18next.


<a name="basicstech-stackmd"></a>

# Tech Stack

Base technology stack and libraries used in projects.


<a name="basicsarchitecturemd"></a>

# Architecture

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


<a name="basicscode-stylemd"></a>

# Code Style

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


<a name="basicsnamingmd"></a>

# Naming

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


<a name="basicsdocumentationmd"></a>

# Documentation

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


<a name="basicstypingmd"></a>

# Typing

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


<a name="appliedproject-structuremd"></a>

# Project Structure

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


<a name="appliedcomponentsmd"></a>

# Components

Rules for creating UI components across all FSD layers.


<a name="appliedtemplates-generationmd"></a>

# Templates & Code Generation

Template tools, syntax, and examples for code generation.


<a name="appliedstylesmd"></a>

# Styles

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


<a name="appliedimages-spritesmd"></a>

# Images


<a name="appliedsvg-spritesmd"></a>

# SVG Sprites


<a name="appliedvideomd"></a>

# Video


<a name="appliedapimd"></a>

# API


<a name="appliedstoresmd"></a>

# Stores


<a name="appliedhooksmd"></a>

# Hooks


<a name="appliedfontsmd"></a>

# Fonts


<a name="appliedlocalizationmd"></a>

# Localization