S.Gromov
b104ca6581
- Переработан раздел 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 с правилами для агентов
177 lines
5.0 KiB
Markdown
177 lines
5.0 KiB
Markdown
<!-- /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 |