DEV Community: MATKARIM MATKARIMOV

Claude Code'ni multi-agent dev jamoaga qanday aylantirdim

MATKARIM MATKARIMOV — Wed, 18 Feb 2026 06:46:50 +0000

Claude Code'ning maxsus agentlari bilan multi-agent ishlab chiqish workflow'ini qurish bo'yicha amaliy qo'llanma — arxitekturadan implementatsiyagacha, real konfiguratsiyalar bilan.

Claude Code'ni 12 ta ixtisoslashtirilgan sub-agentga qanday ajratganim

Men Claude Code (Anthropic'ning CLI vositasi) ni asosiy kodlash yordamchisi sifatida ishlataman. Asl holatda u bitta umumiy maqsadli agent. Lekin men uni 12 ta ixtisoslashtirilgan sub-agentga ajratdim — har birining o'z vazifasi, maxsus vositalari va loyiha konvensiyalarini chuqur bilishi bor.

Natija: hamma narsani yuzaki biladigan bitta agent o'rniga, o'z sohasini chuqur biladigan mutaxassislar jamoasi bor.

Bitta AI agent bilan muammo

Bitta AI agentni hamma narsa uchun ishlatsangiz — kod yozish, review qilish, debug qilish, tiplar yaratish, git boshqarish — oldindan aytish mumkin bo'lgan muammolarga duch kelasiz:

Kontekst suyulanishi: Agent hamma narsa bo'lishga urinadi va har bir vazifada o'rtacha natija beradi
Nomuvofiq patternlar: Qat'iy nazorat bo'lmasa, bir xil pattern turli featurelarda turlicha implement qilinadi
Separation of concerns yo'q: Bir xil agent kod yozadi va uni review qiladi — ikkinchi fikr yo'q
Context window isrof bo'lishi: Har bir prompt barcha ko'rsatmalarning to'liq og'irligini ko'taradi, hatto faqat bitta imkoniyat kerak bo'lsa ham

Yechim aniq edi: kodda ishlatadigan separation of concerns tamoyilini AI workflow'imga ham qo'llash.

Arxitektura: Sub-agentlar qanday ishlaydi

Claude Code ~/.claude/agents/ papkasidagi markdown fayllar orqali maxsus agentlarni qo'llab-quvvatlaydi. Har bir agent asosiy sessiya vazifa topshira oladigan subprocess hisoblanadi.

Asosiy Claude sessiyasi (orkestrator)
  |
  |-- "bu feature'ni qur" topshiradi --> senior-dev agent
  |-- "kodni review qil" topshiradi --> code-reviewer agent
  |-- "tiplar yarat" topshiradi --> schema-type-generator agent
  |-- "commit qil" topshiradi --> git-workflow agent
  |
  (agentlar bir-biri bilan gaplasha olmaydi — faqat asosiy sessiya orqali)

Asosiy cheklovlar:

Agentlar faqat asosiy sessiya bilan muloqot qiladi, hech qachon bir-biri bilan bevosita emas
Har bir agentning o'z tizim prompti, vositalar ruxsati va model tanlovi bor
Asosiy sessiya orkestrator sifatida ishlaydi — qaysi agent qaysi vazifani bajarishini u hal qiladi
Agentlar mustaqil ishlar uchun parallel ishlashi mumkin

12 ta agent

Mana agentlarning to'liq ro'yxati — vazifalari, modellari va vositalari bilan:

Agent	Model	Rang	Vazifasi
`senior-dev`	inherit (Opus)	yashil	Asosiy kod yozuvchi — featurelarni boshidan oxirigacha quradi
`component-architect`	Sonnet	ko'k-yashil	Implementatsiyadan oldin komponent ierarxiyasini loyihalaydi
`code-reviewer`	Sonnet	qizil	Kod sifatini tekshiradi, xatolarni topadi, patternlarni nazorat qiladi
`debugger`	inherit (Opus)	sariq	Runtime xatolar va build muvaffaqiyatsizliklarini tashxislaydi
`api-integrator`	inherit (Opus)	ko'k	Frontendni backend API'larga ulaydi
`schema-type-generator`	Sonnet	binafsha	TypeScript tiplari va Zod schemalarni yaratadi
`test-writer`	inherit (Opus)	yashil	Vitest + Testing Library testlar yozadi
`git-workflow`	Haiku	ko'k	Commitlar, branchlar, PR'larni boshqaradi
`performance-optimizer`	Sonnet	sariq	Performance muammolarini tashxislaydi va tuzatadi
`security-auditor`	Sonnet	qizil	Xavfsizlik tekshiruvlari va zaiflik skanerlash
`refactorer`	inherit (Opus)	binafsha	Mavjud xatti-harakatni saqlab kodni qayta tuzadi
`documentation-creator`	Sonnet	ko'k-yashil	Texnik hujjatlar, JSDoc, README fayllar yozadi
`coding-rules`	inherit (Opus)	binafsha-rang	CLAUDE.md'dagi barcha kodlash standartlarini nazorat qiladi

Nima uchun turli modellar?

Har bir vazifa eng kuchli (va qimmat) modelni talab qilmaydi:

Opus — chuqur fikrlash kerak bo'lgan vazifalar uchun: murakkab featurelar yozish, debugging, refaktoring
Sonnet — pattern matching va izchillik kerak bo'lgan vazifalar uchun: kod review, tip generatsiya, xavfsizlik audit
Haiku — oddiy, takroriy vazifalar uchun: git operatsiyalari (commit xabarlari, branch yaratish)

Bu sifatga zarar bermasdan xarajatlarni kamaytiradi.

Agent anatomiyasi: Har bir agent faylining ichida nima bor

Har bir agent — YAML frontmatter va batafsil tizim promptli markdown fayl. Mana tuzilishi:

---
name: agent-nomi
description: >
  Bu agentni qachon ishlatish kerak. Claude buni qaysi
  agentga topshirishni hal qilish uchun o'qiydi.
model: inherit | sonnet | haiku
color: green
tools: Read, Write, Grep, Glob, Bash
memory: user
---

[Loyihaga xos patternlar, bosqichma-bosqich workflow'lar,
 kod misollari va sifat cheklistlari bilan batafsil tizim prompt]

description maydoni muhim — u asosiy Claude sessiyasiga qachon bu agentni ishlatishni aytadi. Uni routing qoidasi deb o'ylang.

Chuqur tahlil: Asosiy agentlar

1. senior-dev — Implementatsiya ishchisi

Bu production kod yozadigan agent. Uning tizim prompti mening aniq stek va patternlarimni kodlaydi:

## Ish tartibi

### 1-bosqich: Tushunish
Bitta qator kod yozishdan oldin:
1. Talabni diqqat bilan o'qing
2. Noaniq bo'lsa, aniqlashtiruvchi savollar bering

### 2-bosqich: O'rganish
3. Codebase'da o'xshash komponentlarni topish uchun Glob ishlating
4. Bir xil patternga amal qiladigan 2-3 ta mavjud faylni o'qing
5. Qayta ishlatilishi mumkin bo'lgan umumiy utilitalarni tekshiring

### 3-bosqich: Rejalashtirish
6. Yaratadigan yoki o'zgartiradigan barcha fayllarni sanab o'ting
7. Davom etishdan oldin bu rejani foydalanuvchiga taqdim eting

### 4-bosqich: Qurish
9.  Avval tiplar va enumlarni yarating (data kontrakti)
10. i18n validatsiya bilan Zod schemalar yarating
11. Service layerni quríng (ENDPOINTS + featureService)
12. TanStack Query hooklarni quríng (key factory + hooklar)
13. UI komponentlarni eng oxirida quríng

### 5-bosqich: Tekshirish
15. Xatolarni topish uchun har bir faylni qayta o'qing
16. Tip tekshiruvi uchun tsc --noEmit ishga tushiring
17. Formatlash uchun Biome ishga tushiring

Asosiy tushuncha: agent pastdan yuqoriga quradi — avval tiplar, keyin schemalar, keyin servicelar, keyin hooklar, keyin UI. Har bir qatlam faqat o'zidan pastdagi qatlamlarga bog'liq. Bu tartib yuqoridan pastga qurishda paydo bo'ladigan kaskad tip xatolarining oldini oladi.

Har bir pattern aniq kod misollarini o'z ichiga oladi. Mana service layer pattern agent prompti ichida qanday ko'rinadi:

const ENDPOINTS = {
  LIST: '/users/list',
  CREATE: '/users/create',
  UPDATE: (id: number) => `/users/${id}/update`,
  DELETE: (id: number) => `/users/${id}/delete`,
  DETAIL: (id: number) => `/users/${id}`,
} as const;

export const userService = {
  getList: async (filter: UserFilter): Promise<UserListResponse> => {
    const { data } = await axiosClient.post(ENDPOINTS.LIST, filter);
    return data;
  },
  // ... boshqa metodlar
};

Agent "user boshqaruvini qur" so'rovini ko'rganda improvizatsiya qilmaydi — u aynan shu patternga amal qiladi, chunki misollar uning ko'rsatmalariga joylashtirilgan.

2. code-reviewer — Ikkinchi ko'z

Bu agent ataylab Sonnetda (Opus emas) ishlaydi. Kod review — bu pattern matching: bu kod qoidalarga amal qiladimi? Sonnet tezroq, arzonroq va bunga juda yaxshi.

Review jarayoni sistematik:

## Review jarayoni

### 2-qadam: Xato tahlili
Sistematik tekshiring:

**Null/Undefined xavflari:**
- Potentsial undefined qiymatlarda optional chaining yo'q
- TanStack Query `data` ga `isLoading` tekshirmasdan murojaat qilish

**Mantiqiy xatolar:**
- useEffect yoki TanStack Query queryFn'da eskirgan closurelar
- Noto'g'ri skipToken shartlari

**TypeScript muammolari:**
- `any` tip ishlatish (`unknown` yoki aniq tip bo'lishi kerak)
- Zod schemalarida `satisfies z.ZodType<Type>` yo'q

### 5-qadam: Pattern muvofiqlik
Har bir patternni sistematik tekshiring:
- Service layer: ENDPOINTS as const + featureService + axiosClient
- TanStack Query: key factorylar + skipToken + keepPreviousData
- Zod: createSchema(t: TFunction) + satisfies
- CVA: cva() + VariantProps + cn()
- Enumlar: const as const + tip ajratish

Uning chiqishi jiddiylik darajalari bilan tuzilgan:

## Kritik muammolar
- **[BUG]** `user.service.ts:45` - API javobida null tekshiruv yo'q

## Pattern buzilishlar
- **[QUERY]** `use-users.ts:12` - Sahifalangan so'rovda keepPreviousData yo'q

## Xulosa
**O'ZGARISH TALAB QILINADI** - 2 ta kritik xato topildi

3. debugger — Xato detektivi

Biror narsa buzilganda, bu agent qat'iy tashxis jarayoniga amal qiladi. Uning prompti mening stekimga xos har bir keng tarqalgan xato patternini o'z ichiga oladi:

## Management-System'ga xos xato patternlari

### Axios Interceptor xatolari
**Token yangilash muvaffaqiyatsizligi (cheksiz 401 sikli):**
- Asosiy sabab: Token yangilash so'rovi 401 qaytaradi, bu yana yangilashni boshlaydi
- Tekshiring: src/lib/axios.ts dagi Axios interceptorni o'qing
- Tuzatish: Bir vaqtda yangilashlarning oldini olish uchun isRefreshing bayrog'i qo'shing

### TanStack Query xatolari
**skipToken noto'g'ri ishlatilishi (so'rov kerak bo'lmaganda ishlaydi):**
- Asosiy sabab: queryFn undefined parametr oladi, chunki skipToken sharti noto'g'ri
- Tekshiring: skipToken sharti aynan param mavjud bo'lmaganda mos kelishi kerak

### React Hook Form + Zod xatolari
**Schema validatsiya ishlamayapti:**
- Asosiy sabab: createSchema t funksiyasiz chaqirilgan
- Tuzatish: Schema'ni t mavjud bo'lgan komponent ichida yarating

Taxmin qilish o'rniga, agent xatoni ma'lum patternlarga moslashtiradi va asosiy sababni dalillar bilan kuzatadi.

4. schema-type-generator — Tiplar va validatsiya

Bu agent bitta narsaga ixtisoslashgan: loyihaning aniq konvensiyalariga amal qiladigan TypeScript tiplari va Zod schemalar yaratish.

// U enum patternini biladi
export const DepartmentStatus = {
  Active: 'ACTIVE',
  Inactive: 'INACTIVE',
  Archived: 'ARCHIVED',
} as const;

export type DepartmentStatus = (typeof DepartmentStatus)[keyof typeof DepartmentStatus];
export const DepartmentStatusValues = Object.values(DepartmentStatus);

// U schema factory patternini biladi
export const createDepartmentSchema = (t: TFunction) =>
  z.object({
    name: z.string({ message: t('validation.required') })
      .min(2, t('validation.minLength', { min: 2 })),
    status: z.enum(DepartmentStatusValues as [string, ...string[]], {
      message: t('validation.required'),
    }),
  }) satisfies z.ZodType<DepartmentInput>;

export type DepartmentFormValues = z.infer<ReturnType<typeof createDepartmentSchema>>;

Nima uchun tiplar uchun alohida agent? Chunki tip ta'riflari qatlamlar orasidagi kontrakt hisoblanadi. Agar tiplar noto'g'ri bo'lsa, pastdagi hamma narsa buziladi. Loyihaning tip patternlarini (ayniqsa const as const enum pattern va createSchema(t) factory pattern) chuqur tushunadigan mutaxassisga ega bo'lish tipga bog'liq xatolarni sezilarli darajada kamaytiradi.

5. git-workflow — Xavfsiz commit qiluvchi

Bu Haikuda — eng arzon, eng tez modelda ishlaydi. Git operatsiyalari formulaga asoslangan: statusni tekshirish, fayllarni staging'ga qo'shish, conventional commit xabar yozish, push qilish.

## Xavfsizlik qoidalari (HECH QACHON buzilmasin)
- HECH QACHON main/master'ga force push qilmang
- HECH QACHON foydalanuvchining aniq tasdig'isiz git reset --hard ishlatmang
- HECH QACHON .env fayllar yoki credentiallarni staging'ga qo'shmang
- DOIMO commit qilishdan oldin staging'dagi o'zgarishlarni ko'rib chiqing
- DOIMO git add'da aniq fayl yo'llarini ishlating (git add . emas)

Commit xabar formati majburiy:

feat(departments): add department creation form with validation
fix(table): correct column resize handle position
refactor(api): extract shared error handling to Axios interceptor

Orkestratsiya oqimi

Mana oddiy feature so'rovi agentlar orqali qanday o'tadi:

Foydalanuvchi: "CRUD bilan bo'limlar boshqaruvi sahifasini qo'sh"

1. Asosiy sessiya so'rovni tahlil qiladi
2. component-architect'ga topshiradi:
   "Bo'limlar feature uchun komponent ierarxiyasini loyihala"
   -> Qaytaradi: komponent daraxti, proplar, state egaligi xaritasi

3. schema-type-generator'ga topshiradi:
   "Bo'limlar uchun tiplar va Zod schemalar yarat"
   -> Qaytaradi: types.ts + department.schema.ts

4. senior-dev'ga topshiradi:
   "Arxitektura rejasiga amal qilib bo'limlar feature'ni implement qil"
   -> Qaytaradi: service, hooklar, komponentlar, sahifa

5. code-reviewer'ga topshiradi:
   "Barcha yangi bo'limlar feature fayllarini review qil"
   -> Qaytaradi: muammolar bilan review

6. Agar muammolar topilsa, senior-dev'ga qaytaradi:
   "Kod review'dagi muammolarni tuzat"

7. git-workflow'ga topshiradi:
   "Bo'limlar feature'ni commit qil"
   -> Qaytaradi: conventional commit yaratildi

2 va 3-qadamlar mustaqil bo'lgani uchun parallel ishlashi mumkin. Asosiy sessiya ketma-ketlikni boshqaradi.

Umumiy bilim qatlami: coding-rules agent

Bitta maxsus agent hamma narsani birlashtiradi: coding-rules. Bu loyihamning barcha kodlash standartlarini kodlaydigan 2700+ qatorli hujjat:

## Agent identifikatsiyasi

Siz kodlash standartlarini nazorat qilish mutaxassisisiz.
Siz hech qachon yangi patternlar o'ylab topmaysiz — faqat mavjudlarini qat'iy nazorat qilasiz.

Sizning falsafangiz:
- Afzalliklarga nisbatan izchillik
- Avval pattern, keyin implementatsiya
- Improvizatsiya yo'q
- Ishonchsiz bo'lganda agentlarga murojaat qiling

Bu agent boshqa agentlar murojaat qiladigan "haqiqat manbai" vazifasini bajaradi. senior-dev komponent qurganda, u code-reviewer tekshiradigan bir xil CVA patternga amal qiladi va bu coding-rulesdagi misollar bilan mos keladi.

Sozlash: Konfiguratsiya

Agent fayllari

Har bir agent ~/.claude/agents/ da joylashgan:

~/.claude/agents/
  senior-dev.md
  code-reviewer.md
  component-architect.md
  debugger.md
  api-integrator.md
  schema-type-generator.md
  test-writer.md
  git-workflow.md
  performance-optimizer.md
  security-auditor.md
  refactorer.md
  documentation-creator.md
  coding-rules.md

CLAUDE.md — Loyiha konteksti

~/.claude/CLAUDE.md fayli barcha agentlar meros qilib oladigan loyiha darajasidagi kontekstni ta'minlaydi:

# Tech Stack
- React 19 + TypeScript 5.9 + Vite 7
- TanStack Query v5, TanStack Table v8
- React Hook Form + Zod (i18n validation)
- Axios (auth interceptors, token refresh)
- i18next (en, ru, uz, uz-Cyrl)
- Biome (linter + formatter)

# Quick Reference
- TypeScript: strict mode, interface for objects, type for unions
- Service Layer: ENDPOINTS as const + featureService + axiosClient
- TanStack Query: key factories, skipToken, keepPreviousData
- Zod: createSchema(t: TFunction), satisfies z.ZodType<T>
- Files: feature-based src/features/[name]/

Ruxsatlar

~/.claude/settings.json agentlarning nima qila olishini boshqaradi:

{
  "permissions": {
    "allow": [
      "Bash(npm:*)", "Bash(pnpm:*)", "Bash(git:*)",
      "Bash(biome:*)", "Bash(vitest:*)", "Bash(tsc:*)",
      "WebSearch", "WebFetch"
    ],
    "defaultMode": "acceptEdits"
  }
}

Agentlar bu ruxsatlarni meros qilib oladi. code-reviewer faqat Read, Grep, Glob, Bash ga ega — tahlil qila oladi lekin yoza olmaydi. senior-dev to'liq vositalar ruxsatiga ega.

Nimalarni o'rgandim

1. Agent descriptionlari routing qoidalari

YAML frontmatterdagi description maydoni Claude qaysi agentni ishlatishni hal qilish usuli. Uni funksiya signaturasi kabi yozing: aniq kirishlar, aniq foydalanish holatlari.

# Yomon
description: Kod bilan yordam beradi

# Yaxshi
description: >
  Ekspert kod review agenti. Kod sifatini tekshiradi, xatolarni topadi,
  TypeScript tip xavfsizligini tasdiqlaydi va loyiha patternlariga
  (service layer, TanStack Query, Zod i18n, CVA, Biome) muvofiqligini tekshiradi.
  Kod o'zgarishlaridan keyin yoki commitlardan oldin proaktiv ishlating.

2. Aniq misollar abstrakt qoidalardan ustun

"To'g'ri TypeScript patternlar ishlating" o'rniga, aniq kodni joylashtiring:

// Bu agent promptining ichida:
export const Role = {
  Admin: 'ADMIN',
  User: 'USER',
} as const;

export type Role = (typeof Role)[keyof typeof Role];

Agent bu patternni aynan qayta ishlab chiqaradi.

3. Model tanlovi narx uchun muhim

Mening git-workflow agentim oyiga yuzlab marta ishlaydi. Oddiy commit xabarlari uchun Opus o'rniga Haiku ishlatish sifat yo'qolishisiz sezilarli xarajatni tejaydi.

4. Reviewerlar uchun faqat o'qish vositalari

code-reviewer agentida faqat Read, Grep, Glob, Bash bor — Write yoki Edit yo'q. Bu ataylab. Reviewer tahlil qilishi va hisobot berishi kerak, tuzatish emas. Tuzatish senior-devga qaytadi.

5. Memory sessiyalar aro o'rganishni yoqadi

Har bir agentda memory: user bor, ya'ni ular sessiyalar bo'ylab patternlar va afzalliklarni eslab qolishi mumkin. debugger agenti qaysi xato patternlarni ko'rganini eslaydi; senior-dev sizning afzal qiladigan komponent tuzilmangizni eslaydi.

Oldin va keyin

Oldin (bitta agent):

"Users sahifasini qur" → Umumiy implementatsiya, loyiha patternlari yo'q
Pattern buzilishlarni topish uchun qo'lda review kerak
Featurelar bo'ylab nomuvofiq kod
Har bir prompt konvensiyalarni takrorlashni talab qiladi

Keyin (12 ta ixtisoslashtirilgan agent):

"Users sahifasini qur" → senior-dev aniq patternlarga amal qiladi, pastdan yuqoriga quradi
code-reviewer buzilishlarni avtomatik topadi
Har bir feature bir xil patternlarga amal qiladi
Konvensiyalar agent promptlariga joylashtirilgan, hech qachon takrorlanmaydi

O'zingiz sinab ko'ring

Loyihangizning asosiy patternlarini aniqlang (eng ko'p nazorat qiladigan 3-5 ta pattern)
Birinchi agentingizni yarating: senior-dev — kod yozuvchidan boshlang
Patternlaringizga qarshi tekshiradigan code-reviewer qo'shing
Qaysi vazifalar fokuslantirilgan promptlardan foyda ko'rishini payqaganingizda asta-sekin mutaxassislar qo'shing
Haqiqat manbai sifatida umumiy coding-rules agentini saqlang

Birinchi kundan 12 ta agent kerak emas. 2-3 tadan boshlang va patternlaringiz mustahkamlanganida agentlarni o'shiring.

Bu setup hali takomillashtirilmoqda — men hali ham agent promptlarini yaxshilayapman, model tanlovlarini sozlayapman. Agar takliflaringiz bo'lsa, kamchilik sezgan bo'lsangiz yoki boshqacha yondashuv bilan o'xshash narsa qurgan bo'lsangiz, izohlarda yozishingiz mumkin.

How I Turned Claude Code Into a Multi-Agent Dev Team

MATKARIM MATKARIMOV — Wed, 18 Feb 2026 06:40:23 +0000

A practical guide to building a multi-agent development workflow with Claude Code's custom agents — from architecture to implementation, with real configs.

I use Claude Code (Anthropic's CLI tool) as my primary coding assistant. Out of the box, it's a single general-purpose agent. But I've split it into 12 specialized sub-agents, each with a focused role, specific tools, and deep knowledge of my project's conventions.

The result: instead of one agent that kind of knows everything, I have a team of specialists that deeply know their domain.

The Problem With a Single AI Agent

When you use a single AI agent for everything — writing code, reviewing it, debugging, creating types, managing git — you run into predictable issues:

Context dilution: The agent tries to be everything and becomes mediocre at each task
Inconsistent patterns: Without strict enforcement, the same pattern gets implemented differently across features
No separation of concerns: The same agent writes code and reviews it — there's no second opinion
Wasted context window: Every prompt carries the full weight of all instructions, even when you only need a specific capability

The fix was obvious: apply the same separation of concerns principle I use in code to my AI workflow.

Architecture: How Sub-Agents Work

Claude Code supports custom agents via markdown files in ~/.claude/agents/. Each agent is a subprocess that the main session can delegate tasks to.

Main Claude Session (orchestrator)
  |
  |-- delegates "build this feature" --> senior-dev agent
  |-- delegates "review the code" --> code-reviewer agent
  |-- delegates "create types" --> schema-type-generator agent
  |-- delegates "commit changes" --> git-workflow agent
  |
  (agents cannot talk to each other — only through main session)

Key constraints:

Agents communicate only with the main session, never directly with each other
Each agent has its own system prompt, tool access, and model selection
The main session acts as an orchestrator — it decides which agent handles which task
Agents can run in parallel for independent work

The 12 Agents

Here's my full agent roster with their roles, models, and tool access:

Agent	Model	Color	Role
`senior-dev`	inherit (Opus)	green	Primary code writer — builds features end-to-end
`component-architect`	Sonnet	cyan	Designs component hierarchy before implementation
`code-reviewer`	Sonnet	red	Reviews code quality, catches bugs, enforces patterns
`debugger`	inherit (Opus)	yellow	Diagnoses runtime errors and build failures
`api-integrator`	inherit (Opus)	blue	Connects frontend to backend APIs
`schema-type-generator`	Sonnet	magenta	Creates TypeScript types and Zod schemas
`test-writer`	inherit (Opus)	green	Writes Vitest + Testing Library tests
`git-workflow`	Haiku	blue	Handles commits, branches, PRs
`performance-optimizer`	Sonnet	yellow	Diagnoses and fixes performance issues
`security-auditor`	Sonnet	red	Security reviews and vulnerability scanning
`refactorer`	inherit (Opus)	magenta	Restructures code while preserving behavior
`documentation-creator`	Sonnet	cyan	Writes technical docs, JSDoc, README files
`coding-rules`	inherit (Opus)	purple	Enforces all coding standards from CLAUDE.md

Why Different Models?

Not every task needs the most powerful (and expensive) model:

Opus for tasks that need deep reasoning: writing complex features, debugging, refactoring
Sonnet for tasks that need pattern matching and consistency: reviewing code, generating types, auditing security
Haiku for simple, repetitive tasks: git operations (commit messages, branch creation)

This keeps costs down without sacrificing quality where it matters.

Agent Anatomy: What's Inside Each Agent File

Every agent is a markdown file with YAML frontmatter and a detailed system prompt. Here's the structure:

---
name: agent-name
description: >
  When to use this agent. Claude reads this to decide
  which agent to delegate to.
model: inherit | sonnet | haiku
color: green
tools: Read, Write, Grep, Glob, Bash
memory: user
---

[Detailed system prompt with project-specific patterns,
 step-by-step workflows, code examples, and quality checklists]

The description field is critical — it tells the main Claude session when to use this agent. Think of it as a routing rule.

Deep Dive: Key Agents

1. senior-dev — The Implementation Workhorse

This is the agent that writes production code. Its system prompt encodes my exact stack and patterns:

## Workflow

### Phase 1: Understand
Before writing a single line of code:
1. Read the requirement carefully
2. If ambiguous, ask clarifying questions

### Phase 2: Explore
3. Use Glob to find similar components in the codebase
4. Read 2-3 existing files that follow the same pattern
5. Check for shared utilities you can reuse

### Phase 3: Plan
6. List all files you will create or modify
7. Present this plan to the user before proceeding

### Phase 4: Build
9.  Create types and enums first (data contract)
10. Create Zod schemas with i18n validation
11. Build the service layer (ENDPOINTS + featureService)
12. Build TanStack Query hooks (key factory + hooks)
13. Build the UI components last

### Phase 5: Verify
15. Read back every file to catch errors
16. Run tsc --noEmit for type checking
17. Run Biome for formatting

The key insight: the agent builds bottom-up — types first, then schemas, then services, then hooks, then UI. Each layer depends only on the layers below it. This order prevents the cascading type errors you get when building top-down.

Every pattern includes concrete code examples. Here's what the service layer pattern looks like inside the agent prompt:

const ENDPOINTS = {
  LIST: '/users/list',
  CREATE: '/users/create',
  UPDATE: (id: number) => `/users/${id}/update`,
  DELETE: (id: number) => `/users/${id}/delete`,
  DETAIL: (id: number) => `/users/${id}`,
} as const;

export const userService = {
  getList: async (filter: UserFilter): Promise<UserListResponse> => {
    const { data } = await axiosClient.post(ENDPOINTS.LIST, filter);
    return data;
  },
  // ... other methods
};

When the agent sees a "build user management" request, it doesn't improvise — it follows this exact pattern because the examples are embedded in its instructions.

2. code-reviewer — The Second Pair of Eyes

This agent runs on Sonnet (not Opus) intentionally. Code review is pattern-matching: does this code follow the rules? Sonnet is faster, cheaper, and excellent at this.

The review process is systematic:

## Review Process

### Step 2: Bug Analysis
Systematically check for:

**Null/Undefined Risks:**
- Optional chaining missing on potentially undefined values
- TanStack Query `data` accessed without checking `isLoading`

**Logic Errors:**
- Stale closures in useEffect or TanStack Query queryFn
- Incorrect skipToken conditions

**TypeScript Issues:**
- `any` type usage (should be `unknown` or specific)
- Missing `satisfies z.ZodType<Type>` on Zod schemas

### Step 5: Pattern Compliance
Verify each pattern systematically:
- Service layer: ENDPOINTS as const + featureService + axiosClient
- TanStack Query: key factories + skipToken + keepPreviousData
- Zod: createSchema(t: TFunction) + satisfies
- CVA: cva() + VariantProps + cn()
- Enums: const as const + type extraction

Its output is structured with severity levels:

## Critical Issues
- **[BUG]** `user.service.ts:45` - Missing null check on API response

## Pattern Violations
- **[QUERY]** `use-users.ts:12` - Missing keepPreviousData on paginated query

## Verdict
**REQUEST CHANGES** - 2 critical bugs found

3. debugger — The Error Detective

When something breaks, this agent follows a strict diagnostic process. Its prompt includes every common error pattern specific to my stack:

## Management-System Specific Error Patterns

### Axios Interceptor Errors
**Token Refresh Failure (infinite 401 loop):**
- Root cause: Token refresh request returns 401, triggering another refresh
- Check: Read the Axios interceptor in src/lib/axios.ts
- Fix: Add isRefreshing flag to prevent concurrent refresh calls

### TanStack Query Errors
**skipToken Misuse (query fires when it should not):**
- Root cause: queryFn receives undefined param because skipToken condition is wrong
- Check: The skipToken condition must match exactly when param is unavailable

### React Hook Form + Zod Errors
**Schema Validation Not Triggering:**
- Root cause: createSchema called without t function
- Fix: Create schema inside component where t is available

Instead of guessing, the agent matches the error against known patterns and traces the root cause with evidence.

4. schema-type-generator — Types and Validation

This agent specializes in one thing: creating TypeScript types and Zod schemas that follow the project's exact conventions.

// It knows the enum pattern
export const DepartmentStatus = {
  Active: 'ACTIVE',
  Inactive: 'INACTIVE',
  Archived: 'ARCHIVED',
} as const;

export type DepartmentStatus = (typeof DepartmentStatus)[keyof typeof DepartmentStatus];
export const DepartmentStatusValues = Object.values(DepartmentStatus);

// It knows the schema factory pattern
export const createDepartmentSchema = (t: TFunction) =>
  z.object({
    name: z.string({ message: t('validation.required') })
      .min(2, t('validation.minLength', { min: 2 })),
    status: z.enum(DepartmentStatusValues as [string, ...string[]], {
      message: t('validation.required'),
    }),
  }) satisfies z.ZodType<DepartmentInput>;

export type DepartmentFormValues = z.infer<ReturnType<typeof createDepartmentSchema>>;

Why a separate agent for types? Because type definitions are the contract between layers. If the types are wrong, everything downstream breaks. Having a specialist that deeply understands the project's type patterns (especially the const as const enum pattern and the createSchema(t) factory pattern) reduces type-related bugs significantly.

5. git-workflow — The Safe Committer

This runs on Haiku — the cheapest, fastest model. Git operations are formulaic: check status, stage files, write a conventional commit message, push.

## Safety Rules (NEVER break these)
- NEVER force push to main/master
- NEVER use git reset --hard without explicit user confirmation
- NEVER stage .env files or credentials
- ALWAYS review staged changes before committing
- ALWAYS use specific file paths in git add (not git add .)

The commit message format is enforced:

feat(departments): add department creation form with validation
fix(table): correct column resize handle position
refactor(api): extract shared error handling to Axios interceptor

The Orchestration Flow

Here's how a typical feature request flows through the agents:

User: "Add a departments management page with CRUD"

1. Main session analyzes the request
2. Delegates to component-architect:
   "Design the component hierarchy for departments feature"
   -> Returns: component tree, props, state ownership map

3. Delegates to schema-type-generator:
   "Create types and Zod schemas for departments"
   -> Returns: types.ts + department.schema.ts

4. Delegates to senior-dev:
   "Implement the departments feature following the architecture plan"
   -> Returns: service, hooks, components, page

5. Delegates to code-reviewer:
   "Review all new departments feature files"
   -> Returns: review with issues

6. If issues found, delegates back to senior-dev:
   "Fix the issues from the code review"

7. Delegates to git-workflow:
   "Commit the departments feature"
   -> Returns: conventional commit created

Steps 2 and 3 can run in parallel since they're independent. The main session handles the sequencing.

The Shared Knowledge Layer: coding-rules Agent

One special agent ties everything together: coding-rules. It's a 2700+ line document that encodes every coding standard from my project:

## Agent Identity

You are a coding standards enforcement specialist.
You never invent new patterns — you strictly enforce existing ones.

Your philosophy:
- Consistency over preference
- Pattern first, implementation second
- No improvisation
- Reference agents when unsure

This agent serves as the "source of truth" that other agents reference. When the senior-dev builds a component, it follows the same CVA pattern that code-reviewer checks against, which matches the examples in coding-rules.

Setting It Up: Configuration

Agent Files

Each agent lives in ~/.claude/agents/:

~/.claude/agents/
  senior-dev.md
  code-reviewer.md
  component-architect.md
  debugger.md
  api-integrator.md
  schema-type-generator.md
  test-writer.md
  git-workflow.md
  performance-optimizer.md
  security-auditor.md
  refactorer.md
  documentation-creator.md
  coding-rules.md

CLAUDE.md — The Project Context

The ~/.claude/CLAUDE.md file provides project-level context that all agents inherit:

# Tech Stack
- React 19 + TypeScript 5.9 + Vite 7
- TanStack Query v5, TanStack Table v8
- React Hook Form + Zod (i18n validation)
- Axios (auth interceptors, token refresh)
- i18next (en, ru, uz, uz-Cyrl)
- Biome (linter + formatter)

# Quick Reference
- TypeScript: strict mode, interface for objects, type for unions
- Service Layer: ENDPOINTS as const + featureService + axiosClient
- TanStack Query: key factories, skipToken, keepPreviousData
- Zod: createSchema(t: TFunction), satisfies z.ZodType<T>
- Files: feature-based src/features/[name]/

Permissions

The ~/.claude/settings.json controls what agents can do:

{
  "permissions": {
    "allow": [
      "Bash(npm:*)", "Bash(pnpm:*)", "Bash(git:*)",
      "Bash(biome:*)", "Bash(vitest:*)", "Bash(tsc:*)",
      "WebSearch", "WebFetch"
    ],
    "defaultMode": "acceptEdits"
  }
}

Agents inherit these permissions. The code-reviewer only has Read, Grep, Glob, Bash — it can analyze but not write. The senior-dev has full tool access.

What I've Learned

1. Agent descriptions are routing rules

The description field in the YAML frontmatter is how Claude decides which agent to use. Write it like a function signature: clear inputs, clear use cases.

# Bad
description: Helps with code

# Good
description: >
  Expert code review agent. Reviews code quality, catches bugs,
  verifies TypeScript type safety, and checks adherence to project
  patterns (service layer, TanStack Query, Zod i18n, CVA, Biome).
  Use proactively after code changes or before commits.

2. Concrete examples beat abstract rules

Instead of "use proper TypeScript patterns", embed the exact code:

// This is inside the agent prompt:
export const Role = {
  Admin: 'ADMIN',
  User: 'USER',
} as const;

export type Role = (typeof Role)[keyof typeof Role];

The agent will reproduce this pattern exactly.

3. Model selection matters for cost

My git-workflow agent runs hundreds of times a month. Using Haiku instead of Opus for simple commit messages saves significant cost with zero quality loss.

4. Read-only tools for reviewers

The code-reviewer agent only has Read, Grep, Glob, Bash — no Write or Edit. This is intentional. A reviewer should analyze and report, not fix. The fix goes back to senior-dev.

5. Memory enables cross-session learning

Every agent has memory: user, which means they can remember patterns and preferences across sessions. The debugger agent remembers which error patterns it's seen before; the senior-dev remembers your preferred component structure.

Before and After

Before (single agent):

"Build a users page" → Generic implementation, missing project patterns
Manual review needed to catch pattern violations
Inconsistent code across features
Every prompt required repeating conventions

After (12 specialized agents):

"Build a users page" → senior-dev follows exact patterns, builds bottom-up
code-reviewer catches violations automatically
Every feature follows identical patterns
Conventions are embedded in agent prompts, never repeated

Try It Yourself

Identify your project's core patterns (3-5 patterns you enforce most often)
Create your first agent: start with senior-dev — the code writer
Add a code-reviewer that checks against your patterns
Gradually add specialists as you notice which tasks benefit from focused prompts
Keep a shared coding-rules agent as the source of truth

You don't need 12 agents on day one. Start with 2-3 and grow as your patterns solidify.

This setup is a work in progress — I'm still refining agent prompts, adjusting model choices, and discovering new ways to split responsibilities. If you have suggestions, spot any gaps, or have built something similar with a different approach, I'd love to hear about it in the comments

Website: (https://matkarim.uz)

Feature-Based React Architecture That Actually Scales

MATKARIM MATKARIMOV — Thu, 12 Feb 2026 12:46:13 +0000

A deep dive into building a scalable React 19 enterprise app using feature-based architecture, TanStack Query, Zod with i18n, and a strict service layer pattern.

Introduction

I've been building FlowBoard — a full-featured React SPA for team collaboration, project tracking, and workflow management. After months of iteration, the codebase has grown to 350+ source files across 8 feature modules, supporting 4 languages, with a clean architecture that hasn't slowed me down.

In this article, I'll break down the architecture decisions, folder structure, and patterns that keep this codebase maintainable at scale. Whether you're starting a new project or refactoring an existing one, these patterns can help.

Tech Stack at a Glance:

Layer	Technology
Framework	React 19 + TypeScript 5.9
Build	Vite 7
UI	Radix UI + shadcn/ui + Tailwind CSS v4
Server State	TanStack Query v5
Tables	TanStack Table v8
Forms	React Hook Form + Zod
Routing	React Router 7
HTTP	Axios (interceptors + token refresh)
i18n	react-i18next (4 languages)
Code Quality	Biome (linter + formatter)

The Problem with "File-Type" Organization

Most React tutorials teach you to organize by file type:

src/
├── components/
│   ├── UserList.tsx
│   ├── OrderCard.tsx
│   └── ProductForm.tsx
├── hooks/
│   ├── useUsers.ts
│   ├── useOrders.ts
│   └── useProducts.ts
├── services/
│   ├── userService.ts
│   ├── orderService.ts
│   └── productService.ts
└── types/
    ├── user.ts
    ├── order.ts
    └── product.ts

This works fine until you have 20+ features. Then you're constantly jumping between 6 directories to work on a single feature. Files that change together should live together.

Feature-Based Architecture — The Core Idea

Every feature in the system is a self-contained module:

src/features/[feature-name]/
├── components/           # UI components (PascalCase.tsx)
│   ├── FeatureTable.tsx
│   ├── actions/          # CRUD modal forms
│   │   ├── CreateFeature.tsx
│   │   └── UpdateFeature.tsx
│   └── badges/           # Status/Priority badges
├── hooks/                # TanStack Query hooks (kebab-case.ts)
│   └── use-feature.ts
├── services/             # Pure API calls (kebab-case.service.ts)
│   └── feature.service.ts
├── schema/               # Zod validation (kebab-case.schema.ts)
│   └── feature.schema.ts
├── types.ts              # TypeScript interfaces
├── utils/                # Feature-specific helpers
│   ├── config.ts
│   └── table-config.ts
└── index.ts              # Public exports (optional)

The rule is simple: if a file is only used by one feature, it belongs in that feature's folder.

Full Project Structure

Here's the folder tree that powers the entire application:

flowboard/
│
├── public/                         # Static assets (favicon, etc.)
├── src/
│   ├── assets/                     # Images, SVGs, logos
│   │
│   ├── components/                 # ~100 shared components
│   │   ├── ui/                     # 30+ Radix-based primitives
│   │   │   ├── button.tsx
│   │   │   ├── input.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── drawer.tsx
│   │   │   ├── badge.tsx
│   │   │   ├── card.tsx
│   │   │   ├── select.tsx
│   │   │   ├── tooltip.tsx
│   │   │   ├── avatar.tsx
│   │   │   └── ...
│   │   │
│   │   ├── common/                 # App-level shared components
│   │   │   ├── modal.tsx           # Responsive Dialog/Drawer
│   │   │   ├── sidebar.tsx
│   │   │   ├── search-input.tsx
│   │   │   ├── language-switcher.tsx
│   │   │   ├── theme-toggle.tsx
│   │   │   ├── alert-modal.tsx
│   │   │   └── lazy-component.tsx
│   │   │
│   │   ├── data-table/             # Reusable data table system
│   │   │   ├── data-table.tsx      # Main TanStack Table wrapper
│   │   │   ├── toolbar.tsx
│   │   │   ├── column-header.tsx
│   │   │   ├── pagination.tsx
│   │   │   ├── data-export.tsx     # CSV/Excel export
│   │   │   ├── table-settings.tsx
│   │   │   ├── hooks/
│   │   │   └── utils/
│   │   │
│   │   ├── form-inputs/            # ~14 specialized form inputs
│   │   │   ├── file-uploader.tsx
│   │   │   ├── date-picker.tsx
│   │   │   ├── date-range-picker.tsx
│   │   │   ├── multi-select.tsx
│   │   │   ├── searchable-select.tsx
│   │   │   ├── avatar-uploader.tsx
│   │   │   └── ...
│   │   │
│   │   ├── auth/                   # Route guards
│   │   └── navigation/             # Nav menu components
│   │
│   ├── features/                   # 8 self-contained feature modules
│   │   ├── auth/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── schema/
│   │   │   └── types.ts
│   │   │
│   │   ├── tickets/                # Largest feature (~24 components)
│   │   │   ├── components/
│   │   │   │   ├── TicketsTable.tsx
│   │   │   │   ├── KanbanBoard.tsx
│   │   │   │   ├── TicketDetail.tsx
│   │   │   │   ├── actions/
│   │   │   │   │   ├── CreateTicket.tsx
│   │   │   │   │   ├── UpdateTicket.tsx
│   │   │   │   │   └── DeleteTicket.tsx
│   │   │   │   └── badges/
│   │   │   │       ├── StatusBadge.tsx
│   │   │   │       └── PriorityBadge.tsx
│   │   │   ├── hooks/
│   │   │   │   ├── use-tickets.ts
│   │   │   │   ├── use-ticket-queries.ts
│   │   │   │   └── use-ticket-mutations.ts
│   │   │   ├── services/
│   │   │   │   └── tickets.service.ts
│   │   │   ├── schema/
│   │   │   │   └── tickets.schema.ts
│   │   │   ├── utils/
│   │   │   │   ├── config.ts
│   │   │   │   └── table-config.ts
│   │   │   └── types.ts
│   │   │
│   │   ├── workspaces/
│   │   ├── groups/
│   │   ├── members/
│   │   ├── divisions/
│   │   ├── account/
│   │   └── overview/
│   │
│   ├── pages/                      # ~18 route entry points
│   │   ├── auth/
│   │   │   └── Login.tsx
│   │   ├── overview/
│   │   │   ├── Overview.tsx
│   │   │   └── Analytics.tsx
│   │   ├── manage/
│   │   │   ├── Divisions.tsx
│   │   │   ├── Workspaces.tsx
│   │   │   ├── Groups.tsx
│   │   │   └── Members.tsx
│   │   ├── tickets/
│   │   │   ├── CreateTicket.tsx
│   │   │   ├── TicketDetail.tsx
│   │   │   ├── KanbanBoard.tsx
│   │   │   └── TicketsTable.tsx
│   │   └── errors/
│   │       ├── 403.tsx
│   │       ├── 404.tsx
│   │       └── 500.tsx
│   │
│   ├── hooks/                      # ~15 shared custom hooks
│   │   ├── use-auth-context.ts
│   │   ├── use-media-query.ts
│   │   ├── use-mobile.ts
│   │   ├── use-debounce.ts
│   │   ├── use-disclosure.ts
│   │   ├── use-theme.ts
│   │   ├── use-upload.ts
│   │   └── ...
│   │
│   ├── providers/                  # Context providers
│   │   ├── auth-provider.tsx
│   │   ├── theme-provider.tsx
│   │   └── page-title-provider.tsx
│   │
│   ├── context/                    # Context definitions
│   │   ├── auth-context.ts
│   │   ├── sidebar-context.ts
│   │   └── page-title-context.ts
│   │
│   ├── router/                     # Route definitions
│   │   ├── index.tsx
│   │   ├── app-routes.tsx
│   │   └── auth-routes.tsx
│   │
│   ├── layouts/                    # Layout wrappers
│   │   ├── AppLayout.tsx
│   │   └── AuthLayout.tsx
│   │
│   ├── locales/                    # i18n (4 languages)
│   │   ├── en/
│   │   │   ├── common.json
│   │   │   ├── navigation.json
│   │   │   ├── features/
│   │   │   │   ├── auth.json
│   │   │   │   ├── tickets.json
│   │   │   │   ├── workspaces.json
│   │   │   │   ├── members.json
│   │   │   │   └── ...
│   │   │   └── index.ts
│   │   ├── ru/                     # Same structure
│   │   ├── es/                     # Same structure
│   │   └── fr/                     # Same structure
│   │
│   ├── services/                   # Global services
│   │   ├── refresh-token.ts
│   │   └── upload.service.ts
│   │
│   ├── plugins/                    # Axios client setup
│   │   └── axios.ts
│   │
│   ├── types/                      # Shared type definitions
│   │   ├── common.ts
│   │   ├── enums.ts
│   │   └── navigation.ts
│   │
│   ├── utils/                      # Utility files
│   │   ├── token.ts
│   │   ├── format.ts
│   │   ├── permissions.ts
│   │   ├── enum-helpers.ts
│   │   └── zod-helpers.ts
│   │
│   ├── lib/
│   │   └── utils.ts                # cn() class merging
│   │
│   ├── styles/                     # Global CSS
│   ├── config/                     # App configuration
│   ├── main.tsx                    # Entry point
│   ├── App.tsx                     # Root component
│   └── i18n.ts                     # i18next config
│
├── biome.json                      # Linter + Formatter
├── vite.config.ts                  # Build config
├── tsconfig.json                   # TypeScript config
├── components.json                 # shadcn/ui registry
├── package.json
├── Dockerfile
├── docker-compose.yml
└── index.html

By the numbers:

~350 source files
~200 .tsx components + ~110 .ts files
~44 translation JSON files
~100 shared components
8 feature modules
~15 custom hooks

Pattern #1: The Service Layer — API Calls Only

Services are the thinnest possible layer between your app and the backend. They contain zero business logic — just API calls.

// src/features/tickets/services/tickets.service.ts

import { axiosClient } from '@/plugins/axios';
import type { TicketCreate, TicketUpdate, TicketFilter } from '../types';

const ENDPOINTS = {
  CREATE: '/tickets',
  SEARCH: '/tickets/search',
  BY_ID: (id: string) => `/tickets/${id}`,
  STATUS: '/tickets/status',
} as const;

export const ticketService = {
  create: async (data: TicketCreate) => {
    const { data: response } = await axiosClient.post(
      ENDPOINTS.CREATE,
      data
    );
    return response;
  },

  getList: async (filter: TicketFilter) => {
    const { data: response } = await axiosClient.post(
      ENDPOINTS.SEARCH,
      filter
    );
    return response;
  },

  getById: async (id: string) => {
    const { data: response } = await axiosClient.get(
      ENDPOINTS.BY_ID(id)
    );
    return response;
  },

  update: async (id: string, data: TicketUpdate) => {
    const { data: response } = await axiosClient.put(
      ENDPOINTS.BY_ID(id),
      data
    );
    return response;
  },

  delete: async (id: string) => {
    const { data: response } = await axiosClient.delete(
      ENDPOINTS.BY_ID(id)
    );
    return response;
  },
};

Why this matters:

Services are trivially testable (mock axios, assert calls)
Endpoint URLs are centralized and typed
The { data: response } destructure strips the axios wrapper — consumers get clean data
No try/catch here — error handling belongs in components or query hooks

Pattern #2: TanStack Query Hooks with Key Factories

Query key management is critical. Without a system, you'll invalidate the wrong queries and have stale data bugs everywhere.

// src/features/tickets/hooks/use-tickets.ts

import { useQuery, skipToken, keepPreviousData } from '@tanstack/react-query';
import { useMemo } from 'react';
import { ticketService } from '../services/tickets.service';

// Key factory — single source of truth
export const ticketKeys = {
  all: ['tickets'] as const,
  lists: () => [...ticketKeys.all, 'list'] as const,
  list: (filter: TicketFilter) => [...ticketKeys.lists(), filter] as const,
  details: () => [...ticketKeys.all, 'detail'] as const,
  detail: (id: string) => [...ticketKeys.details(), id] as const,
};

export function useTicketList(filter?: TicketFilter) {
  const { data, isLoading, isFetching, isRefetching, error, refetch } =
    useQuery({
      queryKey: filter ? ticketKeys.list(filter) : ticketKeys.lists(),
      queryFn: filter ? () => ticketService.getList(filter) : skipToken,
      placeholderData: keepPreviousData,
    });

  return useMemo(
    () => ({
      tickets: data?.data ?? [],
      total: data?.total ?? 0,
      isLoading,    // true only on initial load
      isFetching,   // true on any fetch (including background)
      isRefetching,  // true only on refetch
      error,
      refetch,
      isEmpty: !isLoading && !data?.data?.length,
    }),
    [data, isLoading, isFetching, error, refetch, isRefetching]
  );
}

Key decisions:

skipToken over enabled: false — Type-safe conditional queries. When filter is undefined, the query doesn't run.
keepPreviousData — When changing pages or filters, the old data stays visible while new data loads. No loading spinners on pagination.
Three loading states — isLoading (first load), isFetching (any fetch), isRefetching (manual refetch). Each drives different UI:
- isLoading → Show skeleton
- isFetching → Show subtle spinner in toolbar
- isRefetching → Show "Refreshing..." text
useMemo on return — Prevents unnecessary re-renders in consuming components. Without this, every TanStack Query internal state change creates a new object reference.
isEmpty computed property — Components don't need to figure out empty state logic themselves.

Pattern #3: Zod Schemas with i18n Validation Messages

Most projects hardcode English validation messages. In a multi-language app, that's a non-starter. Here's how we solve it:

// src/features/tickets/schema/tickets.schema.ts

import type { TFunction } from 'i18next';
import { z } from 'zod';

export const createTicketSchema = (t: TFunction) => {
  return z.object({
    title: z
      .string({ message: t('tickets.fields.title.validation.required') })
      .min(3, t('tickets.fields.title.validation.minLength', { min: 3 })),

    workspaceId: z
      .string({ message: t('tickets.fields.workspace.validation.required') })
      .min(1, t('tickets.fields.workspace.validation.required')),

    priority: z.nativeEnum(TicketPriority, {
      message: t('tickets.fields.priority.validation.required'),
    }),

    description: z.string().optional(),
    deadline: z.string().optional(),
  });
};

export type TicketCreateSchema = z.infer<ReturnType<typeof createTicketSchema>>;

// Usage in component
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { useTranslation } from 'react-i18next';

function CreateTicketForm() {
  const { t } = useTranslation();

  const form = useForm<TicketCreateSchema>({
    resolver: zodResolver(createTicketSchema(t)),
    defaultValues: {
      title: '',
      workspaceId: '',
      priority: 'MEDIUM',
    },
  });

  // ...
}

The key insight: Zod schemas are factory functions that receive t(). This means:

Validation messages are translated in real-time
When users switch languages, form errors update immediately
The schema factory pattern is fully type-safe

Translation file structure:

{
  "tickets": {
    "fields": {
      "title": {
        "label": "Ticket title",
        "placeholder": "Enter ticket title...",
        "validation": {
          "required": "Title is required",
          "minLength": "Title must be at least {{min}} characters"
        }
      }
    }
  }
}

Pattern #4: Type-Safe Enums Without the `enum` Keyword

TypeScript's enum has well-known issues (tree-shaking, type widening, runtime objects). We use const as const instead:

// src/types/enums.ts

export const TicketPriority = {
  Low: 'LOW',
  Medium: 'MEDIUM',
  High: 'HIGH',
  Urgent: 'URGENT',
} as const;

export type TicketPriority = (typeof TicketPriority)[keyof typeof TicketPriority];
// Result: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'

export const TicketPriorityValues = Object.values(TicketPriority);
// Result: ['LOW', 'MEDIUM', 'HIGH', 'URGENT']


export const UserRole = {
  Admin: 'ADMIN',
  Manager: 'MANAGER',
  Lead: 'LEAD',
  Member: 'MEMBER',
  Viewer: 'VIEWER',
} as const;

export type UserRole = (typeof UserRole)[keyof typeof UserRole];
export const UserRoleValues = Object.values(UserRole);

Why this works better:

Fully tree-shakeable
TicketPriority works as both a value (object) and a type (union)
TicketPriorityValues gives you an iterable array for dropdowns/selects
Works seamlessly with Zod's z.nativeEnum()

Pattern #5: Responsive Modal — One Component, Two UIs

On desktop, users expect centered modals. On mobile, bottom drawers feel more natural. Our Modal component handles both:

// src/components/common/modal.tsx (simplified)

import { useMediaQuery } from '@/hooks/use-media-query';
import * as Dialog from '@radix-ui/react-dialog';
import { Drawer } from 'vaul';

export function Modal({ children, ...props }) {
  const isDesktop = useMediaQuery('(min-width: 768px)');

  if (isDesktop) {
    return <Dialog.Root {...props}>{children}</Dialog.Root>;
  }

  return <Drawer.Root {...props}>{children}</Drawer.Root>;
}

// Matching sub-components for each context
export function ModalContent({ children, className, ...props }) {
  const isDesktop = useMediaQuery('(min-width: 768px)');

  if (isDesktop) {
    return (
      <Dialog.Content className={cn('...dialog-styles', className)} {...props}>
        {children}
      </Dialog.Content>
    );
  }

  return (
    <Drawer.Content className={cn('...drawer-styles', className)} {...props}>
      {children}
    </Drawer.Content>
  );
}

Usage is identical regardless of screen size:

<Modal open={isOpen} onOpenChange={setIsOpen}>
  <ModalContent className="md:min-w-2xl">
    <ModalHeader>
      <ModalTitle>{t('tickets.create.title')}</ModalTitle>
    </ModalHeader>
    <ModalBody>
      <TicketForm />
    </ModalBody>
    <ModalFooter>
      <Button onClick={handleSubmit}>{t('common.save')}</Button>
    </ModalFooter>
  </ModalContent>
</Modal>

Pattern #6: Axios Interceptors for Auth

Token management is handled at the HTTP layer, not in every API call:

// src/plugins/axios.ts (simplified)

import axios from 'axios';
import { tokenUtils } from '@/utils/token';
import { refreshTokenFn } from '@/services/refresh-token';

export const axiosClient = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
});

// Request: Inject token
axiosClient.interceptors.request.use((config) => {
  const token = tokenUtils.getAccessToken();
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Response: Handle 401 with token refresh
axiosClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    const originalRequest = error.config;

    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;
      await refreshTokenFn();
      return axiosClient(originalRequest);
    }

    return Promise.reject(error);
  }
);

This means:

Services never deal with tokens
401 errors automatically trigger token refresh
Failed requests are retried transparently
Components are completely unaware of auth headers

Pattern #7: i18n That Scales to 4+ Languages

With 4 languages and 8 features, translation management could become chaotic. Here's our structure:

src/locales/
├── en/
│   ├── common.json          # Shared: "Save", "Cancel", "Delete"...
│   ├── navigation.json      # Menu items
│   ├── features/
│   │   ├── auth.json
│   │   ├── tickets.json
│   │   ├── workspaces.json
│   │   ├── members.json
│   │   ├── groups.json
│   │   ├── divisions.json
│   │   └── overview.json
│   └── index.ts             # Auto-merge all files
├── ru/                      # Same structure
├── es/                      # Same structure
└── fr/                      # Same structure

The index.ts auto-merge:

// src/locales/en/index.ts
import common from './common.json';
import navigation from './navigation.json';
import auth from './features/auth.json';
import tickets from './features/tickets.json';
// ... all features

export default {
  ...common,
  ...navigation,
  ...auth,
  ...tickets,
  // ...
};

Key rules:

No hardcoded strings — Every visible text uses t('key')
common.json for shared text — "Save", "Cancel", "Loading..." live here once
Feature-scoped keys — tickets.fields.title.label, not titleLabel
Interpolation over concatenation — "{{count}} tickets" not count + " tickets"

Pattern #8: Manual Code Splitting

Instead of relying on Vite's automatic chunking (which creates unpredictable splits), we define chunks explicitly:

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor-react': ['react', 'react-dom', 'react-router'],
          'vendor-ui': [
            '@radix-ui/react-dialog',
            '@radix-ui/react-dropdown-menu',
            '@radix-ui/react-popover',
            '@radix-ui/react-select',
            '@radix-ui/react-tooltip',
            // ... other Radix packages
          ],
          'vendor-data': [
            '@tanstack/react-table',
            '@tanstack/react-query',
          ],
          'vendor-forms': [
            'react-hook-form',
            'zod',
            '@hookform/resolvers',
          ],
          'vendor-utils': [
            'clsx',
            'tailwind-merge',
            'class-variance-authority',
            'date-fns',
            'axios',
            'lucide-react',
          ],
        },
      },
    },
  },
});

Benefits:

Predictable chunk sizes
Vendor chunks are cached long-term (they rarely change)
Feature code changes don't invalidate vendor cache
Easy to analyze bundle composition

The Provider Hierarchy

Order matters. Here's the full nesting:

<StrictMode>
  <ThemeProvider>              {/* Dark/Light mode */}
    <PageTitleProvider>        {/* Document title management */}
      <Suspense fallback={<AppLoader />}>  {/* Code splitting */}
        <App>
          <QueryClientProvider>  {/* TanStack Query cache */}
            <Toaster />          {/* Toast notifications */}
            <RouterProvider />   {/* React Router */}
          </QueryClientProvider>
        </App>
      </Suspense>
    </PageTitleProvider>
  </ThemeProvider>
</StrictMode>

Why this order:

ThemeProvider wraps everything — even the loading state should respect theme
PageTitleProvider is above Suspense — title updates don't need the app loaded
QueryClientProvider is inside App — query client is created once in the component
Suspense catches lazy-loaded route components

Data Table System

The reusable DataTable component is one of the most complex shared pieces, built on TanStack Table v8:

src/components/data-table/
├── data-table.tsx           # Main wrapper (renders <table>)
├── toolbar.tsx              # Search + filters + actions
├── column-header.tsx        # Sortable headers
├── pagination.tsx           # Page navigation
├── data-export.tsx          # Export to Excel/CSV
├── table-settings.tsx       # Column visibility toggles
├── resizer.tsx              # Column resize handles
├── hooks/
│   └── use-data-table.ts   # Table state management
├── utils/
│   └── helpers.ts
└── types.ts                 # DataTable type definitions

Every feature's table reuses this system with minimal boilerplate:

import { DataTable } from '@/components/data-table/data-table';

function TicketsTable() {
  const { tickets, total, isLoading } = useTicketList(filter);

  return (
    <DataTable
      data={tickets}
      columns={ticketColumns}
      totalCount={total}
      isLoading={isLoading}
      toolbar={<TicketsToolbar />}
    />
  );
}

Dark Mode — The Right Way

Every component supports dark mode through Tailwind's dark: prefix:

<div className="
  bg-white dark:bg-gray-900/50
  border-gray-200 dark:border-gray-800
  text-gray-900 dark:text-white
">
  <p className="text-gray-600 dark:text-gray-400">
    Secondary text
  </p>
</div>

The ThemeProvider handles system preference detection and manual toggle. Theme choice persists in localStorage.

Terminal-Style Modal Headers

One design detail I'm particularly happy with — feature modals use decorative terminal-style headers with macOS dots and color-coded gradients:

<ModalHeader className="relative overflow-hidden border-b bg-white p-0 dark:bg-gray-900/50">
  {/* Grid pattern background */}
  <div className="pointer-events-none absolute inset-0 bg-[linear-gradient(...)]" />

  {/* Color gradient overlay */}
  <div className="pointer-events-none absolute inset-0 bg-linear-to-br from-emerald-500/10 via-transparent to-teal-500/10" />

  <div className="relative px-4 py-3 sm:px-6 sm:py-5">
    {/* macOS-style terminal dots */}
    <div className="mb-2 flex items-center gap-2 sm:mb-4">
      <div className="flex gap-1.5">
        <div className="h-2 w-2 rounded-full bg-red-400 sm:h-3 sm:w-3" />
        <div className="h-2 w-2 rounded-full bg-yellow-400 sm:h-3 sm:w-3" />
        <div className="h-2 w-2 rounded-full bg-green-400 sm:h-3 sm:w-3" />
      </div>
      <code className="ml-2 rounded-md bg-gray-100 px-2 py-0.5 text-xs dark:bg-gray-800">
        ticket.create()
      </code>
    </div>

    {/* Icon + Title */}
    <div className="flex items-center gap-3">
      <div className="flex h-10 w-10 items-center justify-center rounded-xl bg-linear-to-br from-emerald-500 to-teal-600 shadow-lg">
        <PlusIcon className="h-5 w-5 text-white" />
      </div>
      <ModalTitle>{t('tickets.create.title')}</ModalTitle>
    </div>
  </div>
</ModalHeader>

Color schemes by action:

Create/Add: emerald-500 → teal-600
Edit/Update: blue-500 → indigo-600
Delete: red-500 → rose-600
View/Info: violet-500 → purple-600

This small touch makes the app feel polished and gives users immediate visual context about what action they're performing.

What I'd Do Differently

1. Start with Zustand earlier. We use Context for auth and sidebar, which works fine but creates unnecessary re-renders. Zustand with useShallow would be more efficient.

2. Co-locate pages with features. Having a separate pages/ directory creates indirection. Each feature could export its own page components.

3. Adopt a monorepo structure. Shared components (data-table, form-inputs, modal) could be a separate package, making them reusable across projects.

Key Takeaways

Feature-based structure scales. Group files by feature, not by type. When you work on "tickets", everything is in one folder.
Service layer = pure API calls. No business logic, no error handling. Just axios calls that return data.
TanStack Query key factories prevent stale data bugs. Centralize keys, use skipToken, return memoized objects.
Zod schema factories with t() give you i18n validation for free. No message duplication across languages.
const as const > enum for tree-shaking and type safety.
Responsive modals (Dialog on desktop, Drawer on mobile) improve UX with zero API changes.
Manual code splitting gives you predictable, cacheable chunks.
Biome over ESLint + Prettier — one tool, faster, less config.

Resources

350 files later, I still open any feature folder and know exactly where everything is. That's the whole point.

Your project won't look like this — and it shouldn't. Steal what works, ignore what doesn't. Happy shipping.

Website

Next.js App Router - Functions API To'liq Qo'llanma

MATKARIM MATKARIMOV — Mon, 09 Feb 2026 10:54:39 +0000

Next.js 15+ da barcha funksiyalar - cookies, headers, redirect, notFound, useRouter, generateMetadata, generateStaticParams, fetch, cacheLife va boshqalar

Next.js App Router - Functions API

Next.js App Router da 30 dan ortiq maxsus funksiyalar mavjud. Bu maqolada ularni kategoriyalar bo'yicha misollar bilan tushuntiraman.

Funksiyalar xaritasi

┌─────────────────────────────────────────────────────────┐
│                  NEXT.JS FUNCTIONS                       │
├──────────────────┬──────────────────┬───────────────────┤
│  SERVER          │  NAVIGATION      │  CLIENT HOOKS     │
│  (Server only)   │  (Server/Client) │  ('use client')   │
├──────────────────┼──────────────────┼───────────────────┤
│  cookies()       │  redirect()      │  useRouter()      │
│  headers()       │  permanentRedirect│ usePathname()    │
│  fetch()         │  notFound()      │  useSearchParams()│
│  connection()    │  forbidden()     │  useParams()      │
│                  │  unauthorized()  │  useLinkStatus()  │
├──────────────────┼──────────────────┼───────────────────┤
│  CACHING         │  GENERATION      │  SEGMENT HOOK     │
├──────────────────┼──────────────────┼───────────────────┤
│  cacheLife()     │  generateMetadata│  useSelectedLayout│
│  cacheTag()      │  generateStatic  │    Segment()      │
│  revalidateTag() │    Params        │  useSelectedLayout│
│  updateTag()     │  generateViewport│    Segments()     │
│  revalidatePath()│  generateSitemaps│                   │
│  after()         │  ImageResponse   │                   │
└──────────────────┴──────────────────┴───────────────────┘

1. `cookies()` - Cookie bilan ishlash

Import: next/headers | Ishlaydi: Server Component, Route Handler, Server Action

import { cookies } from 'next/headers';

Cookie o'qish (Server Component)

export default async function Page() {
  const cookieStore = await cookies(); // await kerak!

  // Bitta cookie olish
  const theme = cookieStore.get('theme');
  // { name: 'theme', value: 'dark' }

  // Cookie borligini tekshirish
  const hasToken = cookieStore.has('token'); // true/false

  // Barcha cookie lar
  const all = cookieStore.getAll();
  // [{ name: 'theme', value: 'dark' }, ...]

  return <p>Mavzu: {theme?.value}</p>;
}

Cookie yozish (Server Action / Route Handler)

// app/actions.ts
'use server';

import { cookies } from 'next/headers';

export async function setTheme(theme: string) {
  const cookieStore = await cookies();

  // Oddiy set
  cookieStore.set('theme', theme);

  // Options bilan
  cookieStore.set('theme', theme, {
    httpOnly: true,      // JS dan o'qib bo'lmaydi
    secure: true,        // Faqat HTTPS
    sameSite: 'lax',     // CSRF himoya
    maxAge: 60 * 60 * 24 * 7, // 7 kun
    path: '/',
  });
}

Cookie o'chirish

'use server';

import { cookies } from 'next/headers';

export async function logout() {
  const cookieStore = await cookies();

  // Usul 1: delete()
  cookieStore.delete('session');

  // Usul 2: bo'sh qiymat
  cookieStore.set('session', '');

  // Usul 3: maxAge = 0
  cookieStore.set('session', '', { maxAge: 0 });
}

Cookie options to'liq ro'yxati

Option	Turi	Tavsif
`name`	`string`	Cookie nomi
`value`	`string`	Cookie qiymati
`expires`	`Date`	Aniq tugash sanasi
`maxAge`	`number`	Umr davomiyligi (soniyalarda)
`domain`	`string`	Qaysi domenda mavjud
`path`	`string`	Qaysi yo'lda mavjud (default: `/`)
`secure`	`boolean`	Faqat HTTPS
`httpOnly`	`boolean`	Faqat HTTP (JS kirish yo'q)
`sameSite`	`'lax'` \	`'strict'` \

2. `headers()` - So'rov headerlari

Import: next/headers | Ishlaydi: Server Component | Faqat o'qish

import { headers } from 'next/headers';

export default async function Page() {
  const headersList = await headers(); // await kerak!

  const userAgent = headersList.get('user-agent');
  const referer = headersList.get('referer');
  const authorization = headersList.get('authorization');
  const acceptLanguage = headersList.get('accept-language');

  return <p>Brauzer: {userAgent}</p>;
}

Header ni boshqa so'rovga uzatish

import { headers } from 'next/headers';

export default async function Page() {
  const authorization = (await headers()).get('authorization');

  // Header ni API so'rovga uzatish
  const res = await fetch('https://api.example.com/user', {
    headers: { authorization: authorization! },
  });
  const user = await res.json();

  return <h1>{user.name}</h1>;
}

Mavjud metodlar

Metod	Qaytaradi	Tavsif
`get(name)`	`string \	null`
`has(name)`	`boolean`	Header borligini tekshirish
`entries()`	`Iterator`	Barcha key/value juftliklari
`keys()`	`Iterator`	Barcha header nomlari
`values()`	`Iterator`	Barcha header qiymatlari
`forEach(fn)`	`void`	Har bir header uchun funksiya

Muhim: headers() faqat o'qish uchun - header yozib bo'lmaydi. Header o'rnatish uchun Route Handler da new Response() ishlatang.

3. `redirect()` va `permanentRedirect()` - Yo'naltirish

Import: next/navigation

`redirect()` - Vaqtinchalik yo'naltirish (307)

import { redirect } from 'next/navigation';

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const team = await fetchTeam(id);

  if (!team) {
    redirect('/login'); // return kerak EMAS
  }

  return <h1>{team.name}</h1>;
}

`permanentRedirect()` - Doimiy yo'naltirish (308)

import { permanentRedirect } from 'next/navigation';

export default async function Page() {
  permanentRedirect('/new-page');
  // Brauzer va qidiruv botlari eski URL ni eslab qoladi
}

Server Action dan redirect

// app/actions.ts
'use server';

import { redirect } from 'next/navigation';

export async function createPost(data: FormData) {
  const post = await db.posts.create({
    data: { title: data.get('title') as string },
  });

  redirect(`/blog/${post.slug}`); // 303 status
}

Farqlari

Funksiya	HTTP Status	Qachon ishlatish
`redirect()`	307 (Server Action da 303)	Login kerak, resurs ko'chdi (vaqtinchalik)
`permanentRedirect()`	308	URL butunlay o'zgardi (doimiy)

Muhim qoidalar

redirect() return yozish shart emas - u never tipini qaytaradi
Server Action va Route Handler da try/catch ichida ishlatmang
Event handler da ishlatmang - useRouter().push() ishlatang
Tashqi URL ga ham yo'naltirish mumkin: redirect('https://google.com')

4. `notFound()` - 404 sahifa

Import: next/navigation | Route ga mos not-found.tsx renderlanadi

import { notFound } from 'next/navigation';

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  if (!post) {
    notFound(); // not-found.tsx renderlanadi, 404 status
  }

  return <h1>{post.title}</h1>;
}

5. `forbidden()` va `unauthorized()` (Experimental)

import { forbidden, unauthorized } from 'next/navigation';

export default async function AdminPage() {
  const session = await verifySession();

  if (!session) {
    unauthorized(); // 401 + unauthorized.tsx
  }

  if (session.role !== 'ADMIN') {
    forbidden();    // 403 + forbidden.tsx
  }

  return <div>Admin Panel</div>;
}

6. `useRouter()` - Client-side navigatsiya

Import: next/navigation | Ishlaydi: Client Component ('use client')

'use client';

import { useRouter } from 'next/navigation';

export default function Dashboard() {
  const router = useRouter();

  return (
    <div>
      {/* Sahifaga o'tish (tarixga qo'shiladi) */}
      <button onClick={() => router.push('/settings')}>
        Sozlamalar
      </button>

      {/* Sahifaga o'tish (tarix almashtiriladi) */}
      <button onClick={() => router.replace('/login')}>
        Login
      </button>

      {/* Joriy sahifani yangilash */}
      <button onClick={() => router.refresh()}>
        Yangilash
      </button>

      {/* Oldindan yuklash */}
      <button onMouseEnter={() => router.prefetch('/heavy-page')}>
        Og'ir sahifa (hover qilganda yuklanadi)
      </button>

      {/* Orqaga */}
      <button onClick={() => router.back()}>
        Orqaga
      </button>

      {/* Oldinga */}
      <button onClick={() => router.forward()}>
        Oldinga
      </button>
    </div>
  );
}

Barcha metodlar

Metod	Tavsif
`push(href, { scroll })`	Sahifaga o'tish, tarixga qo'shish
`replace(href, { scroll })`	Sahifaga o'tish, tarixni almashtirish
`refresh()`	Joriy sahifani serverdan yangilash
`prefetch(href)`	Sahifani oldindan yuklash
`back()`	Brauzer tarixida orqaga
`forward()`	Brauzer tarixida oldinga

`scroll` parametri

// Sahifa yuqorisiga scroll qilmaydi (default: true)
router.push('/page', { scroll: false });

Xavfsizlik: router.push() ga foydalanuvchi kiritgan URL ni tekshirmasdan bermang - XSS xavfi bor!

7. `usePathname()` - Joriy URL yo'li

'use client';

import { usePathname } from 'next/navigation';

export function Breadcrumbs() {
  const pathname = usePathname();
  // /blog/my-post

  const segments = pathname.split('/').filter(Boolean);
  // ['blog', 'my-post']

  return (
    <nav>
      {segments.map((segment, i) => (
        <span key={i}> / {segment}</span>
      ))}
    </nav>
  );
}

8. `useSearchParams()` - URL query parametrlari

'use client';

import { useSearchParams } from 'next/navigation';

export function SearchFilter() {
  const searchParams = useSearchParams();

  const query = searchParams.get('query');      // "hello"
  const page = searchParams.get('page');         // "2"
  const tags = searchParams.getAll('tag');        // ["react", "next"]
  const hasSort = searchParams.has('sort');       // true/false
  const allParams = searchParams.toString();      // "query=hello&page=2"

  return <p>Qidiruv: {query}, Sahifa: {page}</p>;
}

Muhim: useSearchParams() eng yaqin <Suspense> chegarasigacha client-side rendering ga o'tkazadi.

9. `useParams()` - Dinamik route parametrlari

'use client';

import { useParams } from 'next/navigation';

export function PostHeader() {
  const params = useParams();
  // { slug: 'my-post' } yoki { category: 'react', slug: 'hooks' }

  return <h1>Post: {params.slug}</h1>;
}

Route	URL	useParams()
`app/blog/[slug]/page.tsx`	`/blog/hello`	`{ slug: 'hello' }`
`app/shop/[...slug]/page.tsx`	`/shop/a/b`	`{ slug: ['a', 'b'] }`

10. `useSelectedLayoutSegment()` - Aktiv segment

Layout da qaysi child segment aktiv ekanligini aniqlash:

'use client';

import { useSelectedLayoutSegment } from 'next/navigation';
import Link from 'next/link';

export function NavLink({
  href,
  children,
}: {
  href: string;
  children: React.ReactNode;
}) {
  const segment = useSelectedLayoutSegment();
  // /blog da → 'blog'
  // /about da → 'about'
  // / da → null

  const isActive = href.includes(segment || '');

  return (
    <Link
      href={href}
      style={{ fontWeight: isActive ? 'bold' : 'normal' }}
    >
      {children}
    </Link>
  );
}

11. `useLinkStatus()` - Link holati

Navigatsiya jarayonida vizual feedback berish:

'use client';

import { useLinkStatus } from 'next/link';

export function LoadingIndicator() {
  const { pending } = useLinkStatus();

  return pending ? <span className="spinner" /> : null;
}

12. `fetch()` - Kengaytirilgan fetch

Next.js Web fetch() ni kengaytirgan - server tomonida caching va revalidation qo'shilgan:

export default async function Page() {
  // Default - statik prerendering da keshlanadi
  const data = await fetch('https://api.example.com/posts');

  // Har safar yangi ma'lumot
  const fresh = await fetch('https://api.example.com/posts', {
    cache: 'no-store',
  });

  // 1 soat kesh
  const cached = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 },
  });

  // Tag bilan kesh (revalidateTag bilan yangilash uchun)
  const tagged = await fetch('https://api.example.com/posts', {
    next: { tags: ['posts'] },
  });

  // Majburiy kesh
  const forced = await fetch('https://api.example.com/posts', {
    cache: 'force-cache',
  });
}

`cache` qiymatlari

Qiymat	Tavsif
`'auto'` (default)	Next.js o'zi aniqlaydi
`'no-store'`	Har safar serverdan yangi oladi
`'force-cache'`	Keshdan beradi, yo'q bo'lsa yuklab keshlaydi

`next.revalidate` qiymatlari

Qiymat	Tavsif
`false`	Cheksiz kesh
`0`	Keshlamaslik
`60`	60 soniyada bir yangilash

13. `generateStaticParams()` - Statik sahifalar generatsiyasi

Build vaqtida dinamik route lar uchun sahifalar yaratish:

// app/blog/[slug]/page.tsx

// Build vaqtida qaysi sahifalar yaratilishini aniqlash
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts')
    .then(res => res.json());

  return posts.map(post => ({
    slug: post.slug,
  }));
  // [{ slug: 'post-1' }, { slug: 'post-2' }, ...]
}

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}

Strategiyalar

// 1. Barcha sahifalarni build da yaratish
export async function generateStaticParams() {
  const posts = await fetchAllPosts();
  return posts.map(p => ({ slug: p.slug }));
}

// 2. Faqat mashhurlarini build da, qolganini runtime da
export async function generateStaticParams() {
  const posts = await fetchPopularPosts();
  return posts.slice(0, 10).map(p => ({ slug: p.slug }));
}

// 3. Hech birini build da yaratmaslik (hammasi runtime da)
export async function generateStaticParams() {
  return [];
}

// 4. Generatsiya qilinmaganlarni 404 qilish
export const dynamicParams = false;

Ko'p darajali dinamik segmentlar

// app/products/[category]/layout.tsx
export async function generateStaticParams() {
  return [
    { category: 'electronics' },
    { category: 'clothing' },
  ];
}

// app/products/[category]/[product]/page.tsx
export async function generateStaticParams({
  params: { category },
}: {
  params: { category: string };
}) {
  // Har bir category uchun productlar
  const products = await fetchProducts(category);
  return products.map(p => ({ product: p.id }));
}

14. `generateMetadata()` - SEO Metadata

Statik metadata

import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'Blog',
  description: 'Eng yaxshi blog postlar',
};

export default function Page() {
  return <h1>Blog</h1>;
}

Dinamik metadata

import type { Metadata } from 'next';

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  };
}

Title template

// app/layout.tsx - Root layout
export const metadata: Metadata = {
  title: {
    template: '%s | MySite',   // %s → child title bilan almashadi
    default: 'MySite',         // Child title bo'lmasa
  },
};

// app/about/page.tsx
export const metadata: Metadata = {
  title: 'Biz haqimizda',
};
// Natija: <title>Biz haqimizda | MySite</title>

// app/blog/page.tsx
export const metadata: Metadata = {
  title: {
    absolute: 'Blog',   // Template ni e'tiborsiz qoldiradi
  },
};
// Natija: <title>Blog</title>

To'liq metadata misol

export const metadata: Metadata = {
  // Asosiy
  title: 'Next.js Blog',
  description: 'React framework haqida blog',
  keywords: ['Next.js', 'React', 'TypeScript'],
  authors: [{ name: 'Mehmon', url: 'https://example.com' }],

  // Base URL
  metadataBase: new URL('https://example.com'),

  // Open Graph (Telegram, Facebook)
  openGraph: {
    title: 'Next.js Blog',
    description: 'React framework haqida blog',
    url: 'https://example.com',
    siteName: 'MySite',
    locale: 'uz_UZ',
    type: 'website',
    images: [
      {
        url: '/og-image.png',
        width: 1200,
        height: 630,
        alt: 'Blog rasmi',
      },
    ],
  },

  // Twitter
  twitter: {
    card: 'summary_large_image',
    title: 'Next.js Blog',
    description: 'React framework haqida blog',
    creator: '@mehmon',
    images: ['/twitter-image.png'],
  },

  // Robots
  robots: {
    index: true,
    follow: true,
    googleBot: {
      index: true,
      follow: true,
      'max-image-preview': 'large',
    },
  },

  // Alternates (til versiyalari)
  alternates: {
    canonical: '/',
    languages: {
      'uz-UZ': '/uz',
      'en-US': '/en',
      'ru-RU': '/ru',
    },
  },

  // Verifikatsiya
  verification: {
    google: 'google-site-verification-code',
    yandex: 'yandex-verification-code',
  },

  // Ikonkalar
  icons: {
    icon: '/favicon.ico',
    apple: '/apple-icon.png',
  },

  // Manifest (PWA)
  manifest: '/manifest.json',
};

Metadata birlashtirish qoidasi

app/layout.tsx (title: "MySite", openGraph: { title: "MySite", description: "..." })
    │
    └── app/blog/page.tsx (title: "Blog")
         │
         Natija:
         title = "Blog"                    ← almashtrildi
         openGraph.title = "MySite"        ← meros qoldi (blog da openGraph yo'q)
         openGraph.description = "..."     ← meros qoldi

Qoida: Child segment da maydon belgilansa - almashtiriladi. Belgilanmasa - ota dan meros qoladi.

15. Caching funksiyalari

`cacheLife()` - Kesh muddati

import { cacheLife } from 'next/cache';

async function BlogPosts() {
  'use cache';
  cacheLife('hours'); // 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'max'

  return await fetchPosts();
}

`cacheTag()` + `revalidateTag()` / `updateTag()`

import { cacheTag, revalidateTag, updateTag } from 'next/cache';

// Keshlash va tag qo'yish
async function getPosts() {
  'use cache';
  cacheTag('posts');
  return await fetchPosts();
}

// Server Action - fonda yangilash
async function createPost(data: FormData) {
  'use server';
  await db.posts.create(data);
  revalidateTag('posts'); // stale-while-revalidate
}

// Server Action - darhol yangilash
async function updateCart(itemId: string) {
  'use server';
  await db.cart.update(itemId);
  updateTag('cart'); // darhol keshni tozalash
}

`revalidatePath()` - Yo'l bo'yicha yangilash

import { revalidatePath } from 'next/cache';

export async function createPost() {
  'use server';
  await db.posts.create(...);
  revalidatePath('/blog'); // /blog sahifasini yangilash
}

`after()` - Javobdan keyin ishlatish

So'rov javob yuborilgandan keyin loglar yoki analytics yuborish:

import { after } from 'next/server';

export default async function Page() {
  const data = await fetchData();

  after(async () => {
    // Javob yuborilgandan KEYIN ishlaydi
    await analytics.track('page-view');
    await logger.log('Page rendered');
  });

  return <div>{data}</div>;
}

16. `connection()` - So'rov vaqtiga kechirish

Komponentni so'rov vaqtida ishlashga majburlash:

import { connection } from 'next/server';

async function DynamicContent() {
  await connection(); // Prerendering dan chiqish

  const now = new Date().toISOString();
  const uuid = crypto.randomUUID();

  return <p>{now} - {uuid}</p>;
}

17. `draftMode()` - Qoralama rejim

CMS bilan integratsiya - chop etilmagan kontentni ko'rish:

import { draftMode } from 'next/headers';

export default async function Page() {
  const { isEnabled } = await draftMode();

  const posts = isEnabled
    ? await fetchDraftPosts()   // Qoralama postlar
    : await fetchPublishedPosts(); // Chop etilgan postlar

  return <div>{/* ... */}</div>;
}

Xulosa jadvali

Server funksiyalari (Server Component da ishlatiladi)

Funksiya	Vazifasi	Dinamik rendering ga o'tkazadimi?
`cookies()`	Cookie o'qish/yozish	Ha
`headers()`	So'rov headerlari	Ha
`connection()`	So'rov vaqtiga kechirish	Ha
`draftMode()`	Qoralama rejim	Ha
`after()`	Javobdan keyin kod ishlatish	Yo'q

Navigatsiya funksiyalari (Server va Client da)

Funksiya	Vazifasi	HTTP Status
`redirect()`	Vaqtinchalik yo'naltirish	307 (SA: 303)
`permanentRedirect()`	Doimiy yo'naltirish	308
`notFound()`	404 sahifa	404
`forbidden()`	403 sahifa	403
`unauthorized()`	401 sahifa	401

Client hooklar (`'use client'` da ishlatiladi)

Hook	Vazifasi
`useRouter()`	Programmatik navigatsiya
`usePathname()`	Joriy URL yo'li
`useSearchParams()`	Query parametrlari
`useParams()`	Dinamik route parametrlari
`useLinkStatus()`	Link navigatsiya holati
`useSelectedLayoutSegment()`	Aktiv child segment

Generatsiya funksiyalari

Funksiya	Vazifasi
`generateMetadata()`	SEO metadata
`generateStaticParams()`	Statik sahifalar
`generateViewport()`	Viewport sozlamalari
`generateSitemaps()`	Sitemap generatsiyasi

Keshlash funksiyalari

Funksiya	Vazifasi
`cacheLife()`	Kesh muddati
`cacheTag()`	Kesh tegi
`revalidateTag()`	Fonda yangilash
`updateTag()`	Darhol yangilash
`revalidatePath()`	Yo'l bo'yicha yangilash

Bu maqola Next.js 15+ rasmiy dokumentatsiyasi asosida yozilgan. Savollar yoki takliflar bo'lsa, kommentariyada yozing!
(https://matkarim.uz)

Next.js - File Conventions (Fayl Konventsiyalari) To'liq Qo'llanma

MATKARIM MATKARIMOV — Mon, 09 Feb 2026 10:28:46 +0000

Next.js 15+ da barcha maxsus fayllar - page, layout, loading, error, not-found, route, template, default, forbidden, unauthorized va route segment config

Next.js App Router - File Conventions (Fayl Konventsiyalari)

Next.js app/ papkasi ichida maxsus nomli fayllarni taniydi. Har bir fayl aniq vazifaga ega va Next.js uni avtomatik ravishda to'g'ri joyga render qiladi.

Bu maqolada barcha maxsus fayllarni batafsil misollar bilan tushuntirib beraman.

Umumiy ko'rinish - Barcha maxsus fayllar

app/
├── layout.tsx          # Umumiy layout (qayta renderlanmaydi)
├── template.tsx        # Layout kabi, lekin HAR SAFAR qayta renderlanadi
├── page.tsx            # Sahifa - route ni public qiladi
├── loading.tsx         # Yuklanish holati (Suspense fallback)
├── error.tsx           # Xatolik holati (Error Boundary)
├── global-error.tsx    # Global xatolik (root layout uchun)
├── not-found.tsx       # 404 sahifa
├── global-not-found.tsx # Global 404 (experimental)
├── forbidden.tsx       # 403 sahifa (experimental)
├── unauthorized.tsx    # 401 sahifa (experimental)
├── route.ts            # API endpoint (page bilan birga bo'lmaydi!)
├── default.tsx         # Parallel route fallback
├── [slug]/             # Dinamik segment
├── (group)/            # Route group
└── @slot/              # Parallel route slot

Render tartibi:

<Layout>
  <Template>
    <ErrorBoundary fallback={<Error />}>
      <Suspense fallback={<Loading />}>
        <NotFoundBoundary fallback={<NotFound />}>
          <Page />
        </NotFoundBoundary>
      </Suspense>
    </ErrorBoundary>
  </Template>
</Layout>

1. `page.tsx` - Sahifa

Route ni ommaviy (public) qiladi. Bu faylsiz papka route bo'lmaydi.

// app/blog/[slug]/page.tsx
export default async function Page({
  params,
  searchParams,
}: {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{
    [key: string]: string | string[] | undefined;
  }>;
}) {
  const { slug } = await params;
  const { page = '1', sort = 'asc' } = await searchParams;

  return (
    <div>
      <h1>Blog Post: {slug}</h1>
      <p>Sahifa: {page}, Tartib: {sort}</p>
    </div>
  );
}

Props

Prop	Turi	Tavsif
`params`	`Promise<{...}>`	Dinamik route parametrlari
`searchParams`	`Promise<{...}>`	URL query parametrlari (`?key=value`)

params misollari

Route	URL	params
`app/shop/[slug]/page.tsx`	`/shop/shoes`	`{ slug: 'shoes' }`
`app/shop/[category]/[item]/page.tsx`	`/shop/clothes/shirt`	`{ category: 'clothes', item: 'shirt' }`
`app/shop/[...slug]/page.tsx`	`/shop/a/b/c`	`{ slug: ['a', 'b', 'c'] }`

searchParams misollari

URL	searchParams
`/shop?a=1`	`{ a: '1' }`
`/shop?a=1&b=2`	`{ a: '1', b: '2' }`
`/shop?a=1&a=2`	`{ a: ['1', '2'] }`

PageProps helper (TypeScript)

Import kerak emas - global mavjud:

export default async function Page(
  props: PageProps<'/blog/[slug]'>
) {
  const { slug } = await props.params;
  return <h1>{slug}</h1>;
}

Client Component da `use()` ishlatish

'use client';
import { use } from 'react';

export default function Page({
  params,
  searchParams,
}: {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
}) {
  const { slug } = use(params);       // await emas, use()!
  const { query } = use(searchParams);

  return <h1>{slug} - {query}</h1>;
}

Muhim: Next.js 15+ da params va searchParams Promise. Server Component da await, Client Component da use() ishlatiladi.

2. `layout.tsx` - Layout

Bir nechta sahifalar orasida umumiy UI. Navigatsiyada qayta renderlanmaydi, state saqlanadi.

// app/dashboard/layout.tsx
export default async function DashboardLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ team: string }>;
}) {
  const { team } = await params;

  return (
    <section>
      <header>
        <h1>{team} Dashboard</h1>
      </header>
      <main>{children}</main>
    </section>
  );
}

Props

Prop	Turi	Tavsif
`children`	`React.ReactNode`	Majburiy - sahifa yoki ichki layout
`params`	`Promise<{...}>`	Ixtiyoriy - dinamik route parametrlari

Root Layout - MAJBURIY

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="uz">
      <body>{children}</body>
    </html>
  );
}

<html> va <body> bo'lishi shart
<head> ni qo'lda qo'shmang - Metadata API ishlatang

LayoutProps helper

export default function Layout(
  props: LayoutProps<'/dashboard'>
) {
  return <section>{props.children}</section>;
}

Layout ning cheklovlari

Layout navigatsiyada qayta renderlanmaydi, shu sababli:

Muammo	Yechim
`searchParams` ga kirish yo'q	`useSearchParams()` hook (Client Component)
`pathname` ga kirish yo'q	`usePathname()` hook (Client Component)
Child segment ni bilish yo'q	`useSelectedLayoutSegment()` hook
Children ga data uzatish yo'q	Bir xil fetch - React avtomatik deduplicate qiladi

Aktiv navigatsiya misoli:

'use client';
import { usePathname } from 'next/navigation';
import Link from 'next/link';

export function NavLinks() {
  const pathname = usePathname();

  return (
    <nav>
      <Link
        href="/"
        className={pathname === '/' ? 'active' : ''}
      >
        Bosh sahifa
      </Link>
      <Link
        href="/about"
        className={pathname === '/about' ? 'active' : ''}
      >
        Biz haqimizda
      </Link>
    </nav>
  );
}

Child segment ni aniqlash:

'use client';
import { useSelectedLayoutSegment } from 'next/navigation';

export function NavLink({
  slug,
  children,
}: {
  slug: string;
  children: React.ReactNode;
}) {
  const segment = useSelectedLayoutSegment();
  const isActive = slug === segment;

  return (
    <Link
      href={`/blog/${slug}`}
      style={{ fontWeight: isActive ? 'bold' : 'normal' }}
    >
      {children}
    </Link>
  );
}

3. `loading.tsx` - Yuklanish holati

page.tsx ni avtomatik <Suspense> bilan o'rab, yuklanish UI ko'rsatadi.

// app/dashboard/loading.tsx
export default function Loading() {
  return (
    <div className="animate-pulse space-y-4">
      <div className="h-8 bg-gray-200 rounded w-1/3" />
      <div className="h-4 bg-gray-200 rounded w-full" />
      <div className="h-4 bg-gray-200 rounded w-2/3" />
    </div>
  );
}

Xususiyatlari

Hech qanday props qabul qilmaydi
Default holatda Server Component
Prefetching da fallback UI yuklanadi - navigatsiya darhol bo'ladi
Layout interaktiv bo'lib qoladi
Navigatsiya interruptible - boshqa linkni bosish mumkin

Ichkarida nima bo'layotgani

// Next.js avtomatik shunday qiladi:
<Layout>
  <Suspense fallback={<Loading />}>
    <Page />
  </Suspense>
</Layout>

Qo'lda Suspense ishlatish

Sahifa ichida alohida bo'limlar uchun:

import { Suspense } from 'react';

export default function Page() {
  return (
    <section>
      <Suspense fallback={<p>Feed yuklanmoqda...</p>}>
        <PostFeed />
      </Suspense>
      <Suspense fallback={<p>Ob-havo yuklanmoqda...</p>}>
        <Weather />
      </Suspense>
    </section>
  );
}
// PostFeed va Weather PARALLEL yuklanadi!

4. `error.tsx` - Xatolik holati

Route segment ni Error Boundary bilan o'rab, xatolik UI ko'rsatadi.

Majburiy: 'use client' bo'lishi shart!

// app/dashboard/error.tsx
'use client';

import { useEffect } from 'react';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // Xatolikni logging servisga yuborish
    console.error(error);
  }, [error]);

  return (
    <div>
      <h2>Xatolik yuz berdi!</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>
        Qayta urinish
      </button>
    </div>
  );
}

Props

Prop	Turi	Tavsif
`error`	`Error & { digest?: string }`	Xatolik obyekti
`error.message`	`string`	Dev da to'liq, prod da umumiy xabar
`error.digest`	`string`	Server loglarida moslashtirish uchun hash
`reset`	`() => void`	Error boundary ni qayta render qilish

`global-error.tsx` - Root layout xatoliklari uchun

Root layout dagi xatoliklarni ushlaydi. O'z <html> va <body> teglari bo'lishi shart:

// app/global-error.tsx
'use client';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <html>
      <body>
        <h2>Jiddiy xatolik!</h2>
        <button onClick={() => reset()}>Qayta urinish</button>
      </body>
    </html>
  );
}

5. `not-found.tsx` - 404 sahifa

notFound() funksiyasi chaqirilganda ko'rsatiladigan UI:

// app/not-found.tsx
import Link from 'next/link';

export default function NotFound() {
  return (
    <div>
      <h2>Topilmadi</h2>
      <p>So'ralgan resurs topilmadi</p>
      <Link href="/">Bosh sahifaga qaytish</Link>
    </div>
  );
}

Async bo'lishi mumkin

import Link from 'next/link';
import { headers } from 'next/headers';

export default async function NotFound() {
  const headersList = await headers();
  const domain = headersList.get('host');
  const data = await getSiteData(domain);

  return (
    <div>
      <h2>Topilmadi: {data.name}</h2>
      <Link href="/blog">Barcha postlar</Link>
    </div>
  );
}

`global-not-found.tsx` (Experimental v15.4+)

Butun ilova uchun 404. Ko'p root layout bo'lganda kerak:

// next.config.ts
const nextConfig = {
  experimental: { globalNotFound: true },
};

// app/global-not-found.tsx
export default function GlobalNotFound() {
  return (
    <html lang="uz">
      <body>
        <h1>404 - Sahifa topilmadi</h1>
      </body>
    </html>
  );
}

6. `template.tsx` - Template (qayta renderlash)

Layout kabi, lekin navigatsiyada har safar qayta renderlanadi. State resetlanadi, useEffect qayta ishlaydi:

// app/dashboard/template.tsx
export default function Template({
  children,
}: {
  children: React.ReactNode;
}) {
  return <div>{children}</div>;
}

Layout vs Template

Xususiyat	Layout	Template
Navigatsiyada qayta render	Yo'q	Ha
State saqlanishi	Ha	Yo'q (resetlanadi)
useEffect qayta ishlashi	Yo'q	Ha
DOM qayta yaratilishi	Yo'q	Ha

Qachon Template ishlatish kerak?

Har navigatsiyada useEffect qayta ishlashi kerak bo'lganda
Child komponentlar state ni resetlash kerak bo'lganda
Suspense fallback ni har navigatsiyada ko'rsatish kerak bo'lganda

// Misol: Har sahifaga o'tganda animatsiya
export default function Template({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="animate-fadeIn">
      {children}
    </div>
  );
}

Render tartibi

<Layout>
  {/* Template unique key oladi - segment o'zgarganda remount */}
  <Template key={routeParam}>
    {children}
  </Template>
</Layout>

7. `route.ts` - API Endpoint (Route Handler)

Web Request/Response API yordamida backend API yaratish:

// app/api/users/route.ts
export async function GET() {
  const users = await db.users.findMany();
  return Response.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return Response.json(user, { status: 201 });
}

Qo'llab-quvvatlanadigan HTTP metodlar

export async function GET(request: Request) {}
export async function POST(request: Request) {}
export async function PUT(request: Request) {}
export async function PATCH(request: Request) {}
export async function DELETE(request: Request) {}
export async function HEAD(request: Request) {}
export async function OPTIONS(request: Request) {}

Dinamik route parametrlari

// app/api/users/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const user = await db.users.findUnique({ where: { id } });

  if (!user) {
    return Response.json(
      { error: 'Topilmadi' },
      { status: 404 }
    );
  }

  return Response.json(user);
}

Cookies va Headers

import { cookies, headers } from 'next/headers';

export async function GET() {
  const cookieStore = await cookies();
  const token = cookieStore.get('token');

  const headersList = await headers();
  const referer = headersList.get('referer');

  return Response.json({ token: token?.value, referer });
}

Query parametrlari

import { type NextRequest } from 'next/server';

export function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get('query');
  // /api/search?query=hello → query = "hello"

  return Response.json({ query });
}

FormData

export async function POST(request: Request) {
  const formData = await request.formData();
  const name = formData.get('name');
  const email = formData.get('email');

  return Response.json({ name, email });
}

Redirect

import { redirect } from 'next/navigation';

export async function GET() {
  redirect('https://nextjs.org/');
}

CORS

export async function GET() {
  return new Response('OK', {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

Streaming

const encoder = new TextEncoder();

async function* makeIterator() {
  yield encoder.encode('Birinchi qism\n');
  await new Promise(r => setTimeout(r, 500));
  yield encoder.encode('Ikkinchi qism\n');
  await new Promise(r => setTimeout(r, 500));
  yield encoder.encode('Uchinchi qism\n');
}

export async function GET() {
  const iterator = makeIterator();
  const stream = new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();
      if (done) controller.close();
      else controller.enqueue(value);
    },
  });

  return new Response(stream);
}

RouteContext helper (TypeScript)

import type { NextRequest } from 'next/server';

export async function GET(
  _req: NextRequest,
  ctx: RouteContext<'/users/[id]'>
) {
  const { id } = await ctx.params;
  return Response.json({ id });
}

Muhim: page.tsx va route.ts bitta papkada birga bo'lishi mumkin emas!

8. `default.tsx` - Parallel Route Fallback

Parallel Routes da to'liq sahifa yuklanishidan keyin slot ning aktiv holatini tiklash mumkin bo'lmaganda fallback sifatida renderlanadi:

// app/@analytics/default.tsx
export default function Default() {
  return <div>Analytics yuklanmoqda...</div>;
}

Qachon kerak?

app/
├── layout.tsx          # @team va @analytics ni render qiladi
├── page.tsx
├── @team/
│   ├── page.tsx        # /
│   ├── settings/
│   │   └── page.tsx    # /settings
│   └── default.tsx     # Fallback
└── @analytics/
    ├── page.tsx        # /
    └── default.tsx     # /settings da analytics yo'q → default ko'rsatiladi

Foydalanuvchi /settings ga kirib sahifani yangilasa:

@team → settings/page.tsx ko'rsatadi
@analytics → settings/ yo'q → default.tsx ko'rsatadi

Muhim: default.tsx bo'lmasa, xatolik chiqadi! Parallel route ishlatganda har doim qo'shing.

9. `forbidden.tsx` va `unauthorized.tsx` (Experimental)

Autentifikatsiya uchun yangi maxsus fayllar:

`forbidden.tsx` - 403 (Taqiqlangan)

// app/forbidden.tsx
import Link from 'next/link';

export default function Forbidden() {
  return (
    <div>
      <h2>403 - Taqiqlangan</h2>
      <p>Bu resursga kirishga ruxsatingiz yo'q.</p>
      <Link href="/">Bosh sahifaga</Link>
    </div>
  );
}

// Ishlatish - page.tsx da
import { forbidden } from 'next/navigation';

export default async function AdminPage() {
  const user = await getUser();
  if (user.role !== 'ADMIN') {
    forbidden(); // 403 status + forbidden.tsx renderlanadi
  }
  return <div>Admin Panel</div>;
}

`unauthorized.tsx` - 401 (Autentifikatsiya talab qilinadi)

// app/unauthorized.tsx
import Login from '@/components/Login';

export default function Unauthorized() {
  return (
    <div>
      <h1>401 - Tizimga kiring</h1>
      <p>Bu sahifani ko'rish uchun tizimga kirishingiz kerak.</p>
      <Login />
    </div>
  );
}

// Ishlatish
import { unauthorized } from 'next/navigation';

export default async function DashboardPage() {
  const session = await verifySession();
  if (!session) {
    unauthorized(); // 401 status + unauthorized.tsx renderlanadi
  }
  return <div>Dashboard</div>;
}

Eslatma: Bu ikkalasi hali experimental - production da ehtiyot bo'ling.

10. Route Segment Config

Sahifa yoki layout ning rendering xatti-harakatini sozlash:

// Har qanday page.tsx yoki layout.tsx da
export const dynamic = 'auto';
export const dynamicParams = true;
export const revalidate = false;
export const fetchCache = 'auto';
export const runtime = 'nodejs';
export const preferredRegion = 'auto';
export const maxDuration = 5;

Har bir option tushuntirilishi

`dynamic`

Qiymat	Ma'nosi
`'auto'`	Default - Next.js o'zi aniqlaydi
`'force-dynamic'`	Har safar dinamik render (SSR)
`'force-static'`	Majburiy statik (cookies/headers bo'sh qaytadi)
`'error'`	Statik, dinamik API ishlatilsa xatolik

`dynamicParams`

Qiymat	Ma'nosi
`true`	`generateStaticParams` da yo'q segmentlar on-demand generatsiya
`false`	Yo'q segmentlar 404 qaytaradi

`revalidate`

Qiymat	Ma'nosi
`false`	Cheksiz kesh (default)
`0`	Har safar dinamik render
`60`	60 soniyada bir qayta tekshirish

`runtime`

Qiymat	Ma'nosi
`'nodejs'`	Node.js runtime (default)
`'edge'`	Edge Runtime (Cache Components bilan ishlamaydi)

`maxDuration`

export const maxDuration = 30; // Server funksiyasi max 30 soniya ishlaydi

Muhim: cacheComponents: true yoqilganda, bu config lar o'rniga use cache + cacheLife ishlatiladi.

11. Dinamik Route Konventsiyalari

Oddiy dinamik segment

app/blog/[slug]/page.tsx      →  /blog/hello-world

Catch-all segment

app/shop/[...slug]/page.tsx   →  /shop/a, /shop/a/b, /shop/a/b/c

Optional catch-all segment

app/docs/[[...slug]]/page.tsx →  /docs, /docs/a, /docs/a/b

12. Route Group va Parallel Route Konventsiyalari

Route Group - `(folder)`

URL da ko'rinmaydi, tartibga solish uchun:

app/(marketing)/about/page.tsx  →  /about
app/(shop)/cart/page.tsx        →  /cart

Parallel Route - `@slot`

Bitta layout da bir nechta sahifani parallel ko'rsatish:

app/
├── layout.tsx          # children + @analytics + @team
├── @analytics/
│   ├── page.tsx
│   └── default.tsx
├── @team/
│   ├── page.tsx
│   └── default.tsx
└── page.tsx

export default function Layout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
}) {
  return (
    <>
      {children}
      <aside>{analytics}</aside>
      <section>{team}</section>
    </>
  );
}

Intercepting Routes

(.)folder    →  shu darajadagi route ni ushlash
(..)folder   →  bir daraja yuqoridagi
(..)(..)folder → ikki daraja yuqoridagi
(...)folder  →  root dan ushlash

Xulosa jadvali

Fayl	Vazifasi	`'use client'` kerakmi	Props
`page.tsx`	Sahifa UI	Yo'q (ixtiyoriy)	`params`, `searchParams`
`layout.tsx`	Umumiy UI (qayta renderlanmaydi)	Yo'q	`children`, `params`
`template.tsx`	Umumiy UI (HAR SAFAR renderlanadi)	Yo'q	`children`
`loading.tsx`	Yuklanish skeleton	Yo'q	Hech narsa
`error.tsx`	Xatolik UI	Ha, majburiy	`error`, `reset`
`global-error.tsx`	Root xatolik UI	Ha, majburiy	`error`, `reset`
`not-found.tsx`	404 UI	Yo'q	Hech narsa
`forbidden.tsx`	403 UI (experimental)	Yo'q	Hech narsa
`unauthorized.tsx`	401 UI (experimental)	Yo'q	Hech narsa
`route.ts`	API endpoint	Yo'q	`request`, `context`
`default.tsx`	Parallel route fallback	Yo'q	`params`

Oltin qoidalar

page.tsx bo'lmasa, papka route emas
page.tsx va route.ts bitta papkada birga bo'lmaydi
error.tsx har doim 'use client' bo'lishi shart
layout.tsx navigatsiyada qayta renderlanmaydi - state saqlanadi
template.tsx har navigatsiyada qayta renderlanadi - state resetlanadi
loading.tsx avtomatik <Suspense> boundary yaratadi
Parallel route larda har doim default.tsx qo'shing
Next.js 15+ da params va searchParams Promise - await yoki use() kerak

Bu maqola Next.js 15+ rasmiy dokumentatsiyasi asosida yozilgan. Savollar yoki takliflar bo'lsa, kommentariyada yozing!
(https://www.matkarim.uz)

Next.js - Cache Components (Partial Prerendering) To'liq Qo'llanma

MATKARIM MATKARIMOV — Mon, 09 Feb 2026 10:26:35 +0000

Next.js 15+ da Cache Components - bitta sahifada statik, keshlangan va dinamik kontentni birlashtirish, use cache, cacheLife, cacheTag va revalidatsiya

Next.js App Router - Cache Components (Partial Prerendering)

Bu Next.js ning eng yangi va eng kuchli xususiyatlaridan biri. Bitta sahifada statik, keshlangan va dinamik kontentni birga ishlatish imkonini beradi.

Muammo: Avvalgi yondashuv

Oddiy server-rendered ilovalarda sahifa ikki xil bo'lishi mumkin edi:

Variant 1: STATIK sahifa - Tez, lekin eskirgan. Build vaqtida yaratiladi, yangi ma'lumot ko'rsatmaydi.

Variant 2: DINAMIK sahifa - Yangi ma'lumot, lekin sekin. Har safar serverda renderlanadi, foydalanuvchi kutadi.

Tanlash kerak edi - TEZLIK yoki YANGILIK? Ikkalasi birga bo'lmasdi.

Yechim: Cache Components

Cache Components bilan ikkalasini birga olasiz:

┌──────────────────────────────────────────┐
│ Header, Nav, Footer    → STATIK (darhol) │
│ Blog postlar, katalog  → KESHLANGAN      │
│ Foydalanuvchi ma'lumot → DINAMIK (stream) │
│                                          │
│ Hammasi BITTA sahifada!                  │
└──────────────────────────────────────────┘

Brauzer darhol statik shell (qobiq) oladi, keyin dinamik qismlar tayyor bo'lganda UI yangilanadi.

Yoqish

Bu opt-in xususiyat. next.config.ts da yoqish kerak:

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
};

export default nextConfig;

3 xil kontent turi

Cache Components yoqilganda sahifadagi har bir komponent 3 xil bo'lishi mumkin:

Tur	Qanday belgilanadi	Static shell da?	Misol
Statik	Avtomatik	Ha - darhol	Header, nav, footer
Keshlangan	`'use cache'` + `cacheLife()`	Ha - darhol	Blog postlar, katalog
Dinamik	`<Suspense>` bilan o'raladi	Yo'q - stream bo'ladi	cookies, shaxsiy ma'lumot

1. Avtomatik statik kontent

Sinxron operatsiyalar, import lar va oddiy hisob-kitoblar avtomatik statik shell ga qo'shiladi. Hech qanday maxsus belgi kerak emas:

// app/page.tsx
import fs from 'node:fs';

export default async function Page() {
  // Sinxron fayl o'qish
  const content = fs.readFileSync('./config.json', 'utf-8');

  // Module import
  const constants = await import('./constants.json');

  // Oddiy hisob-kitob
  const processed = JSON.parse(content).items.map(
    item => item.value * 2
  );

  return (
    <div>
      <h1>{constants.appName}</h1>
      <ul>
        {processed.map((value, i) => (
          <li key={i}>{value}</li>
        ))}
      </ul>
    </div>
  );
}
// Butun sahifa STATIK - darhol ko'rsatiladi

Next.js o'zi aniqlaydi - "bu komponent prerendering da tugaydi" va uni statik shell ga qo'shadi.

Tekshirish: Build natijasini ko'ring yoki brauzerda "View Page Source" qiling - statik kontent HTML da ko'rinadi.

2. Dinamik kontent - `<Suspense>` bilan

Network so'rovlar, DB querylar, asinxron operatsiyalar prerendering da bajarilmaydi. Ularni <Suspense> bilan o'rab, fallback UI berish kerak:

// app/page.tsx
import { Suspense } from 'react';

async function LatestPosts() {
  // Network so'rov - prerendering da bajarilmaydi
  const res = await fetch('https://api.example.com/posts');
  const posts = await res.json();

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

export default function Page() {
  return (
    <>
      {/* STATIK - darhol ko'rsatiladi */}
      <h1>Blog</h1>
      <nav>Navigatsiya</nav>

      {/* DINAMIK - fallback darhol, kontent keyin stream bo'ladi */}
      <Suspense fallback={<p>Postlar yuklanmoqda...</p>}>
        <LatestPosts />
      </Suspense>
    </>
  );
}

Jarayon:

1. Foydalanuvchi sahifani ochadi
2. Darhol ko'radi: "Blog", Navigatsiya, "Postlar yuklanmoqda..."
3. Server API dan ma'lumot oladi (fonda)
4. Tayyor bo'lganda: "Postlar yuklanmoqda..." → haqiqiy postlar ro'yxati

Muhim: Suspense chegarasini iloji boricha komponentga yaqin qo'ying. Shunda chegaradan tashqaridagi kontent statik shell da qoladi.

Bir nechta dinamik bo'limlar bo'lsa, ular parallel renderlanadi:

export default function Page() {
  return (
    <>
      <h1>Dashboard</h1>

      {/* Bu ikkalasi PARALLEL yuklanadi - bir-birini kutmaydi */}
      <Suspense fallback={<p>Statistika...</p>}>
        <Stats />
      </Suspense>

      <Suspense fallback={<p>Grafik...</p>}>
        <Chart />
      </Suspense>
    </>
  );
}

3. Runtime ma'lumotlar - cookies, headers, searchParams

Bu ma'lumotlar faqat so'rov vaqtida mavjud bo'ladi. Har bir foydalanuvchi uchun boshqacha:

import { cookies, headers } from 'next/headers';
import { Suspense } from 'react';

async function UserGreeting() {
  // Runtime data - faqat so'rov vaqtida mavjud
  const cookieStore = await cookies();
  const username = cookieStore.get('username')?.value;

  const headerStore = await headers();
  const lang = headerStore.get('accept-language');

  return <p>Salom, {username}! Tilingiz: {lang}</p>;
}

export default function Page() {
  return (
    <>
      <h1>Dashboard</h1>  {/* STATIK */}

      {/* Runtime data - Suspense MAJBURIY */}
      <Suspense fallback={<p>Yuklanmoqda...</p>}>
        <UserGreeting />
      </Suspense>
    </>
  );
}

Runtime API lari:

API	Ma'lumot
`cookies()`	Foydalanuvchi cookie lari
`headers()`	So'rov headerlari
`searchParams`	URL query parametrlari
`params`	Dinamik route parametrlari

Muhim: Runtime data ni use cache bilan keshlab bo'lmaydi, chunki har bir foydalanuvchi uchun boshqacha.

4. `use cache` - Dinamik ma'lumotni keshlash

Agar dinamik ma'lumot tez-tez o'zgarmasa (blog postlar, mahsulot katalogi), uni use cache bilan keshlab statik shell ga qo'shish mumkin:

// app/page.tsx
import { cacheLife } from 'next/cache';

export default async function Page() {
  'use cache';            // Bu sahifani keshla
  cacheLife('hours');     // 1 soat davomida keshdan beraver

  // Bu fetch bir marta bajariladi, natija keshlanadi
  const users = await db.query('SELECT * FROM users');

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

`cacheLife` profillari

Profil	Ma'nosi
`'seconds'`	Bir necha soniya
`'minutes'`	Bir necha daqiqa
`'hours'`	Soatlar
`'days'`	Kunlar
`'weeks'`	Haftalar
`'max'`	Imkon qadar uzoq

Maxsus konfiguratsiya

import { cacheLife } from 'next/cache';

export default async function Page() {
  'use cache';
  cacheLife({
    stale: 3600,       // 1 soat - eskirgan deb hisoblanguncha
    revalidate: 7200,  // 2 soat - qayta tekshirilguncha
    expire: 86400,     // 1 kun - butunlay o'chirilguncha
  });

  const data = await fetchData();
  return <div>{data}</div>;
}

`use cache` ni funksiya yoki komponent darajasida qo'llash

Faqat sahifa emas, alohida funksiya yoki komponentga ham qo'llash mumkin:

// Komponent darajasida
async function ProductCatalog() {
  'use cache';
  cacheLife('days');

  const products = await fetchProducts();
  return <div>{/* ... */}</div>;
}

// Funksiya darajasida
async function getPopularPosts() {
  'use cache';
  cacheLife('hours');

  return await db.posts.findMany({
    orderBy: { views: 'desc' },
    take: 10,
  });
}

5. Runtime data + `use cache` birga ishlatish

Runtime data va use cache ni bir scope da ishlatib bo'lmaydi. Lekin qiymatni chiqarib, cached funksiyaga argument sifatida uzatish mumkin:

// app/profile/page.tsx
import { cookies } from 'next/headers';
import { Suspense } from 'react';

export default function Page() {
  return (
    <Suspense fallback={<div>Yuklanmoqda...</div>}>
      <ProfileContent />
    </Suspense>
  );
}

// 1-qadam: Runtime data o'qiladi (keshlanmaydi)
async function ProfileContent() {
  const session = (await cookies()).get('session')?.value;

  // Session qiymatini cached komponentga uzatadi
  return <CachedContent sessionId={session!} />;
}

// 2-qadam: KESHLANADI - sessionId cache key bo'ladi
async function CachedContent({
  sessionId,
}: {
  sessionId: string;
}) {
  'use cache';
  // Har xil sessionId uchun alohida kesh yozuvi
  const data = await fetchUserData(sessionId);
  return <div>{data.name} profili</div>;
}

Jarayon:

So'rov keldi → cookies o'qildi → session="abc123"
                                       │
                              Cache da "abc123" bormi?
                              ├── Ha → keshdan javob (tez!)
                              └── Yo'q → fetchUserData("abc123")
                                         → natija keshlanadi
                                         → keyingi safar keshdan

Argumentlar avtomatik ravishda cache key ga aylanadi - turli inputlar uchun alohida kesh yozuvlari yaratiladi.

6. Tag va Revalidatsiya - keshni yangilash

Keshlangan ma'lumotni tag bilan belgilab, keyin yangilash mumkin. Ikki xil usul bor:

`updateTag` - darhol yangilash

Kesh shu zahoti o'chiriladi va yangi ma'lumot olinadi. Savat, like, comment uchun ideal:

// app/actions.ts
import { cacheTag, updateTag } from 'next/cache';

// Keshlangan funksiya
export async function getCart() {
  'use cache';
  cacheTag('cart');       // "cart" tegi bilan belgilash
  return await fetchCart();
}

// Server Action - savatni yangilash
export async function addToCart(itemId: string) {
  'use server';
  await db.cart.add(itemId);
  updateTag('cart');      // "cart" keshini DARHOL yangilash
}

`revalidateTag` - fonda yangilash (stale-while-revalidate)

Eski kesh ko'rsatiladi, fonda yangi ma'lumot yuklanadi. Blog, katalog uchun ideal:

import { cacheTag, revalidateTag } from 'next/cache';

export async function getPosts() {
  'use cache';
  cacheTag('posts');
  return await fetchPosts();
}

export async function createPost(post: FormData) {
  'use server';
  await db.posts.create(post);
  revalidateTag('posts');
  // Foydalanuvchi eski postlarni ko'radi
  // Fonda yangi postlar yuklanadi
  // Keyingi so'rovda yangi postlar ko'rsatiladi
}

Ikki usulning farqi

Metod	Xatti-harakat	Qachon ishlatish
`updateTag('cart')`	Kesh darhol o'chiriladi, yangi ma'lumot shu so'rovda olinadi	Savat, like, comment - darhol ko'rinishi kerak
`revalidateTag('posts')`	Eski kesh ko'rsatiladi, fonda yangilanadi	Blog, katalog - biroz kechikish qabul qilinadi

7. Noaniq operatsiyalar - `connection()`

Math.random(), Date.now(), crypto.randomUUID() kabi operatsiyalar har safar boshqa natija beradi. Ularni so'rov vaqtida ishlashini ta'minlash uchun connection() ishlatiladi:

import { connection } from 'next/server';
import { Suspense } from 'react';

async function UniqueContent() {
  await connection(); // "Bu komponent so'rov vaqtida ishlashi kerak"

  const uuid = crypto.randomUUID();
  const now = new Date().toISOString();

  return (
    <div>
      <p>Unikal ID: {uuid}</p>
      <p>Vaqt: {now}</p>
    </div>
  );
}

export default function Page() {
  return (
    <Suspense fallback={<p>Yuklanmoqda...</p>}>
      <UniqueContent />
    </Suspense>
  );
}

Muhim farq:

use cache ichida Math.random() → bir marta hisoblanadi, keshlanadi (hamma uchun bir xil)
connection() dan keyin Math.random() → har safar yangi qiymat

8. React Activity - navigatsiya state saqlanishi

cacheComponents yoqilganda, Next.js React <Activity> komponentini ishlatadi:

/dashboard dan /settings ga o'tdingiz:

  Dashboard UNMOUNT bo'lmaydi!
  Activity mode = "hidden" bo'ladi
  State saqlanadi (form inputlar, scroll pozitsiya)

/dashboard ga qaytganingizda:
  Dashboard avvalgi holatida qayta ko'rinadi
  Form ma'lumotlari saqlanib qolgan!

Bu degani foydalanuvchi formani to'ldirib yurgan, boshqa sahifaga o'tib qaytsa - hamma narsa saqlanib qoladi.

Next.js yaqinda ko'rilgan bir nechta routeni "hidden" holatda saqlaydi. Eski routelar DOM dan o'chiriladi.

9. To'liq misol - hammasi birga

// app/blog/page.tsx
import { Suspense } from 'react';
import { cookies } from 'next/headers';
import { cacheLife } from 'next/cache';
import Link from 'next/link';

export default function BlogPage() {
  return (
    <>
      {/* 1. STATIK - avtomatik, darhol ko'rsatiladi */}
      <header>
        <h1>Bizning Blog</h1>
        <nav>
          <Link href="/">Bosh sahifa</Link>
          <Link href="/about">Biz haqimizda</Link>
        </nav>
      </header>

      {/* 2. KESHLANGAN - statik shell da, soatlik yangilanadi */}
      <BlogPosts />

      {/* 3. DINAMIK - har bir foydalanuvchi uchun alohida */}
      <Suspense fallback={<p>Sozlamalar yuklanmoqda...</p>}>
        <UserPreferences />
      </Suspense>
    </>
  );
}

// KESHLANGAN - barcha foydalanuvchilar uchun bir xil
async function BlogPosts() {
  'use cache';
  cacheLife('hours');

  const res = await fetch('https://api.vercel.app/blog');
  const posts = await res.json();

  return (
    <section>
      <h2>So'nggi postlar</h2>
      <ul>
        {posts.slice(0, 5).map((post: any) => (
          <li key={post.id}>
            <h3>{post.title}</h3>
            <p>{post.author} - {post.date}</p>
          </li>
        ))}
      </ul>
    </section>
  );
}

// DINAMIK - har bir foydalanuvchi uchun shaxsiy
async function UserPreferences() {
  const theme =
    (await cookies()).get('theme')?.value || 'light';
  const favoriteCategory =
    (await cookies()).get('category')?.value;

  return (
    <aside>
      <p>Mavzu: {theme}</p>
      {favoriteCategory && (
        <p>Sevimli kategoriya: {favoriteCategory}</p>
      )}
    </aside>
  );
}

Foydalanuvchi sahifani ochganda:

Darhol ko'rinadi (statik shell):
┌──────────────────────────────────────┐
│ Bizning Blog                         │ ← STATIK
│ Bosh sahifa | Biz haqimizda          │
│──────────────────────────────────────│
│ So'nggi postlar                      │
│ • Post 1 - Muallif - Sana            │ ← KESHLANGAN
│ • Post 2 - Muallif - Sana            │
│ • Post 3 - Muallif - Sana            │
│──────────────────────────────────────│
│ Sozlamalar yuklanmoqda...            │ ← FALLBACK
└──────────────────────────────────────┘

~0.5 soniya keyin:
┌──────────────────────────────────────┐
│ ...yuqoridagi hamma narsa saqlanadi  │
│──────────────────────────────────────│
│ Mavzu: dark                          │ ← DINAMIK (stream)
│ Sevimli kategoriya: React            │
└──────────────────────────────────────┘

10. Eski route segment config lardan ko'chish

Cache Components yoqilganda eski sozlamalar kerak emas yoki o'zgaradi:

`dynamic = 'force-dynamic'` → O'chirish

// Oldin
export const dynamic = 'force-dynamic';

// Keyin - shunchaki o'chiring, default holatda dinamik
export default function Page() {
  return <div>...</div>;
}

`dynamic = 'force-static'` → `use cache`

// Oldin
export const dynamic = 'force-static';

export default async function Page() {
  const data = await fetch('https://api.example.com/data');
  return <div>...</div>;
}

// Keyin
import { cacheLife } from 'next/cache';

export default async function Page() {
  'use cache';
  cacheLife('max');
  const data = await fetch('https://api.example.com/data');
  return <div>...</div>;
}

`revalidate = 3600` → `cacheLife('hours')`

// Oldin
export const revalidate = 3600;

// Keyin
import { cacheLife } from 'next/cache';

export default async function Page() {
  'use cache';
  cacheLife('hours');
  return <div>...</div>;
}

`fetchCache` → Kerak emas

// Oldin
export const fetchCache = 'force-cache';

// Keyin - use cache ichidagi fetch lar avtomatik keshlanadi
export default async function Page() {
  'use cache';
  return <div>...</div>;
}

`runtime = 'edge'` → Qo'llab-quvvatlanmaydi

Cache Components faqat Node.js runtime da ishlaydi. Edge Runtime qo'llab-quvvatlanmaydi.

Xulosa

Tushuncha	Qanday ishlaydi	Qachon ishlatish
Statik	Avtomatik - hech narsa kerak emas	Header, nav, footer, statik matn
`use cache`	`'use cache'` + `cacheLife()`	DB/API data tez-tez o'zgarmasa
`<Suspense>`	Fallback + stream	Runtime data, shaxsiy ma'lumot
`cacheTag`	Keshni belgilash	Yangilash kerak bo'lgan data
`updateTag`	Darhol yangilash	Savat, like, comment
`revalidateTag`	Fonda yangilash	Blog postlar, katalog
`connection()`	So'rov vaqtiga kechirish	Random, vaqt, UUID
Activity	State saqlanishi	Navigatsiyada form, scroll

Asosiy g'oya

Bitta sahifada statik, keshlangan va dinamik kontent birga yashaydi. Foydalanuvchi darhol statik shell ni ko'radi, dinamik qismlar tayyor bo'lganda stream qilinadi. Bu eng yaxshi foydalanuvchi tajribasini beradi - statik saytning tezligi va dinamik saytning yangiligi birgalikda.

Bu maqola Next.js 15+ rasmiy dokumentatsiyasi asosida yozilgan. Savollar yoki takliflar bo'lsa, kommentariyada yozing!
(https://www.matkarim.uz)

Next.js - Server va Client Componentlar To'liq Qo'llanma

MATKARIM MATKARIMOV — Fri, 06 Feb 2026 13:35:45 +0000

Next.js 15+ da Server va Client Componentlarning farqi, 'use client' chegarasi, Context providerlar, 3rd-party kutubxonalar va xavfsizlik
tags: nextjs, react, webdev, beginners

Next.js App Router - Server va Client Componentlar

Bu mavzu Next.js ning eng muhim tushunchalaridan biri. Komponentlar qayerda renderlanishini tushunish - samarali Next.js ilova yaratishning kaliti.

Server va Client Component nima?

Next.js da barcha komponentlar default holatda Server Component. Client Component qilish uchun faylning yuqorisiga 'use client' yoziladi.

┌─────────────────────────────────────────────────┐
│              SERVER COMPONENT                    │
│  (default - hech narsa yozmasangiz shu)         │
│                                                 │
│  ✅ Ma'lumot olish (fetch, DB)                  │
│  ✅ Maxfiy kalitlar (API_KEY, tokens)           │
│  ✅ JS hajmi kichik (brauzerga JS yuborilmaydi) │
│  ✅ SEO yaxshi                                  │
│                                                 │
│  ❌ useState, useEffect ISHLAMAYDI              │
│  ❌ onClick, onChange ISHLAMAYDI                 │
│  ❌ Browser API (localStorage, window)          │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│              CLIENT COMPONENT                    │
│  ('use client' yozish kerak)                    │
│                                                 │
│  ✅ useState, useEffect                         │
│  ✅ onClick, onChange, onSubmit                  │
│  ✅ Browser API (localStorage, window)          │
│  ✅ Custom hooklar                              │
│                                                 │
│  ❌ async component bo'lolmaydi                 │
│  ❌ Maxfiy kalitlarni foydalanuvchi ko'radi     │
│  ❌ JS hajmi oshadi                             │
└─────────────────────────────────────────────────┘

Qachon qaysi birini ishlatish kerak?

Vazifa	Server	Client
Ma'lumot olish (fetch, DB query)	✅
API kalitlar, tokenlar bilan ishlash	✅
Katta kutubxonalarni server tomonida ishlatish	✅
JS hajmini kamaytirish	✅
State boshqarish (useState)		✅
Event handlerlar (onClick, onChange)		✅
useEffect, lifecycle		✅
Browser API (localStorage, window)		✅
Custom hooklar (useForm, useQuery)		✅

Amaliy misol - Server va Client birgalikda

app/
├── blog/
│   └── [id]/
│       └── page.tsx        # Server Component - ma'lumot oladi
└── ui/
    └── like-button.tsx     # Client Component - interaktiv

// app/blog/[id]/page.tsx - SERVER COMPONENT (default)
// 'use client' YO'Q = Server Component

import LikeButton from '@/app/ui/like-button';
import { getPost } from '@/lib/data';

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post = await getPost(id); // Server da DB/API ga murojaat

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      {/* Server → Client ga props orqali ma'lumot uzatish */}
      <LikeButton likes={post.likes} />
    </div>
  );
}

// app/ui/like-button.tsx - CLIENT COMPONENT
'use client'; // SHU QATOR CLIENT COMPONENT QILADI

import { useState } from 'react';

export default function LikeButton({ likes }: { likes: number }) {
  const [likeCount, setLikeCount] = useState(likes);

  return (
    <button onClick={() => setLikeCount(likeCount + 1)}>
      ❤️ {likeCount}
    </button>
  );
}

Jarayon:

1. Server: Page renderlanadi → post ma'lumoti olinadi
2. Server: LikeButton uchun joy belgilanadi (placeholder)
3. Client: HTML darhol ko'rsatiladi (interaktiv emas hali)
4. Client: Hydration → LikeButton interaktiv bo'ladi
5. Foydalanuvchi: tugmani bosa oladi

`'use client'` qanday ishlaydi - Chegara (Boundary)

'use client' - bu Server va Client orasidagi chegara. Bu faylga import qilingan barcha komponentlar ham Client Component ga aylanadi:

                    'use client' chegarasi
                           │
  SERVER TOMONI            │          CLIENT TOMONI
                           │
  layout.tsx ──────────────┤
  page.tsx ────────────────┤
                           │──── search.tsx ('use client')
                           │        ├── SearchInput.tsx  ← avtomatik Client
                           │        └── SearchResults.tsx ← avtomatik Client
                           │
  header.tsx ──────────────┤
  footer.tsx ──────────────┤

SearchInput va SearchResults da 'use client' yozilmagan bo'lsa ham, ular search.tsx ichida import qilinganligi uchun avtomatik Client Component bo'ladi.

JS hajmini kamaytirish - ENG MUHIM TAMOYIL

Yomon yondashuv - butun Layout ni Client qilish:

// ❌ YOMON - hamma narsa clientga yuboriladi
'use client';

import Search from './search';
import Logo from './logo';

export default function Layout({ children }) {
  return (
    <nav>
      <Logo />      {/* Bu ham Client bo'lib qoladi - keraksiz! */}
      <Search />
    </nav>
  );
}

Yaxshi yondashuv - faqat interaktiv qismni Client qilish:

// ✅ YAXSHI - Layout Server Component bo'lib qoladi
// app/layout.tsx (Server Component)
import Search from './ui/search';  // Client Component
import Logo from './ui/logo';      // Server Component bo'lib qoladi

export default function Layout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <nav>
        <Logo />       {/* Server - JS yuborilmaydi */}
        <Search />     {/* Faqat shu Client */}
      </nav>
      <main>{children}</main>
    </>
  );
}

// app/ui/search.tsx
'use client';

export default function Search() {
  // useState, onChange va boshqa interaktiv logika
}

// app/ui/logo.tsx - 'use client' YO'Q
export default function Logo() {
  return <img src="/logo.svg" alt="Logo" />;
  // Oddiy rasm - serverda renderlanadi, JS yuborilmaydi
}

Natija: Brauzerga faqat Search komponenti uchun JS yuboriladi. Logo, Layout uchun JS yuborilmaydi.

Server Component ni Client Component ichiga joylashtirish

Muammo: Client Component ichida Server Component ni to'g'ridan-to'g'ri import qilib bo'lmaydi:

// ❌ ISHLAMAYDI
'use client';
import ServerComponent from './server-component';

export default function ClientComponent() {
  return <ServerComponent />; // Bu ham Clientga aylanadi!
}

Yechim: children prop orqali uzating:

// app/ui/modal.tsx - CLIENT COMPONENT
'use client';

import { useState } from 'react';

export default function Modal({
  children,
}: {
  children: React.ReactNode;
}) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Ochish</button>
      {isOpen && (
        <div className="modal">
          {children}  {/* Server Component shu yerga kiradi */}
        </div>
      )}
    </>
  );
}

// app/ui/cart.tsx - SERVER COMPONENT
import { getCartItems } from '@/lib/data';

export default async function Cart() {
  const items = await getCartItems(); // Serverda ma'lumot oladi

  return (
    <ul>
      {items.map(item => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

// app/page.tsx - SERVER COMPONENT
import Modal from './ui/modal';
import Cart from './ui/cart';

export default function Page() {
  return (
    <Modal>
      <Cart />
      {/* Cart serverda renderlanadi, keyin Modal ichiga joylashadi */}
    </Modal>
  );
}

Render tartibi:

1. Server: Cart renderlanadi (ma'lumot olinadi) → HTML tayyor
2. Server: Page renderlanadi → Modal placeholder + Cart HTML
3. Client: Modal hydrate bo'ladi → interaktiv
4. Client: Cart HTML o'z joyida — qayta render yo'q

Context Providerlar

React Context Server Component da ishlamaydi. Provider yaratish uchun Client Component kerak:

// app/providers/theme-provider.tsx
'use client';

import { createContext, useState } from 'react';

export const ThemeContext = createContext({
  theme: 'light',
  toggle: () => {},
});

export default function ThemeProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  const [theme, setTheme] = useState('light');

  return (
    <ThemeContext.Provider
      value={{
        theme,
        toggle: () =>
          setTheme(t => (t === 'light' ? 'dark' : 'light')),
      }}
    >
      {children}
    </ThemeContext.Provider>
  );
}

// app/layout.tsx - SERVER COMPONENT
import ThemeProvider from './providers/theme-provider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <ThemeProvider>
          {children}
          {/* children hali ham Server Component bo'lib qoladi */}
        </ThemeProvider>
      </body>
    </html>
  );
}

Muhim: Providerni iloji boricha chuqurroq joylashtiring. <html> ni emas, faqat {children} ni o'rab oling - shunda Next.js statik qismlarni optimizatsiya qila oladi.

Ma'lumotni Server va Client o'rtasida ulashish

React.cache bilan bitta so'rov ichida bir xil ma'lumotni takror yuklamaslik:

// app/lib/user.ts
import { cache } from 'react';

export const getUser = cache(async () => {
  const res = await fetch('https://api.example.com/user');
  return res.json();
});
// 1 ta so'rov ichida necha marta chaqirilsa ham,
// faqat 1 marta fetch bo'ladi

// app/user-provider.tsx
'use client';

import { createContext } from 'react';

type User = { id: string; name: string };

export const UserContext =
  createContext<Promise<User> | null>(null);

export default function UserProvider({
  children,
  userPromise,
}: {
  children: React.ReactNode;
  userPromise: Promise<User>;
}) {
  return (
    <UserContext value={userPromise}>
      {children}
    </UserContext>
  );
}

// app/layout.tsx - SERVER
import UserProvider from './user-provider';
import { getUser } from './lib/user';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const userPromise = getUser(); // await QILMANG!

  return (
    <html>
      <body>
        <UserProvider userPromise={userPromise}>
          {children}
        </UserProvider>
      </body>
    </html>
  );
}

// app/ui/profile.tsx - CLIENT
'use client';

import { use, useContext } from 'react';
import { UserContext } from '../user-provider';

export function Profile() {
  const userPromise = useContext(UserContext);
  const user = use(userPromise!); // use() Promise ni resolve qiladi

  return <p>Xush kelibsiz, {user.name}!</p>;
}

// app/page.tsx - SERVER
import { Suspense } from 'react';
import { Profile } from './ui/profile';

export default function Page() {
  return (
    <Suspense fallback={<div>Yuklanmoqda...</div>}>
      <Profile />
    </Suspense>
  );
}

Server Component ham ishlatishi mumkin:

// app/dashboard/page.tsx - SERVER
import { getUser } from '../lib/user';

export default async function DashboardPage() {
  const user = await getUser(); // cache tufayli qayta fetch bo'lmaydi
  return <h1>Dashboard: {user.name}</h1>;
}

Uchinchi tomon (3rd-party) kutubxonalar

Ba'zi kutubxonalar 'use client' yozmagan bo'lishi mumkin, lekin useState ishlatadi. Bunday holda wrapper yarating:

// ❌ XATO - Carousel useState ishlatadi, lekin 'use client' yo'q
// app/page.tsx (Server Component)
import { Carousel } from 'acme-carousel'; // Error!

export default function Page() {
  return <Carousel />;
}

Yechim - re-export wrapper:

// app/ui/carousel.tsx
'use client';

import { Carousel } from 'acme-carousel';
export default Carousel; // Shunchaki re-export

// app/page.tsx - Endi ishlaydi
import Carousel from './ui/carousel';

export default function Page() {
  return <Carousel />;
}

Muhit xavfsizligi - `server-only` paketi

Server dagi maxfiy kodlar tasodifan clientga tushib qolmasligi uchun:

// ❌ XAVFLI - bu fayl clientda ham import qilinishi mumkin
// lib/data.ts
export async function getData() {
  const res = await fetch('https://api.com/data', {
    headers: {
      authorization: process.env.API_KEY,
      // Clientda bo'sh string bo'ladi!
    },
  });
  return res.json();
}

// ✅ XAVFSIZ - client da import qilsangiz build xatolik beradi
// lib/data.ts
import 'server-only';

export async function getData() {
  const res = await fetch('https://api.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  });
  return res.json();
}

O'rnatish:

pnpm add server-only    # server-only kodni himoyalash
pnpm add client-only    # client-only kodni belgilash

Eslatma: Next.js da faqat NEXT_PUBLIC_ prefiksli environment o'zgaruvchilar clientga yuboriladi. Boshqalari serverda qoladi.

Rendering jarayoni - To'liq rasm

Birinchi yuklash (Initial Load):

SERVER                              CLIENT
──────                              ──────
1. Server Componentlar              4. HTML ko'rsatiladi
   renderlanadi                        (interaktiv emas hali)
         │                                    │
2. RSC Payload yaratiladi           5. RSC Payload bilan
   (binary format)                     Server/Client daraxtlar
         │                             birlashtiriladi
3. HTML pre-render qilinadi                   │
   (Server + Client)               6. Hydration - Client
         │                             Componentlar interaktiv
         └──── yuboriladi ──────►      bo'ladi

Keyingi navigatsiyalar (Subsequent):

SERVER                              CLIENT
──────                              ──────
1. RSC Payload yaratiladi           2. Client Component
   (oldindan prefetch                  FAQAT clientda
    qilingan bo'lishi mumkin)          renderlanadi
         │                                    │
         └──── yuboriladi ──────►   3. DOM yangilanadi
                                       (HTML qayta yuklanmaydi)

Hydration nima?

Hydration - React ning event handler larni DOM ga biriktirish jarayoni. Server dan kelgan statik HTML ni interaktiv qiladi. Tugma bosilishi, input yozilishi - bularning barchasi hydration dan keyin ishlaydi.

Xulosa

Tushuncha	Qoida
Default holat	Server Component
Client Component	`'use client'` yozasiz
`'use client'` chegarasi	Shu fayl + barcha importlari Client bo'ladi
Server → Client ma'lumot	Props orqali (serializable bo'lishi shart)
Server ni Client ichiga	children prop orqali
Context Provider	Client Component sifatida yaratiladi
Maxfiy kodlar himoyasi	`import 'server-only'`
3rd-party kutubxonalar	Wrapper: `'use client'` + re-export
JS hajmini kamaytirish	`'use client'` ni faqat interaktiv componentga

Oltin qoida

'use client' ni iloji boricha past darajada (leaf component da) ishlatang. Shunda Server Component lar ko'p bo'ladi va brauzerga kamroq JS yuboriladi. Bu esa sahifangizni tezlashtiradi va foydalanuvchi tajribasini yaxshilaydi.

Bu maqola Next.js 15+ rasmiy dokumentatsiyasi asosida yozilgan. Savollar yoki takliflar bo'lsa, kommentariyada yozing!

(https://www.matkarim.uz)

Next.js - Linking va Navigatsiya To'liq Qo'llanma

MATKARIM MATKARIMOV — Fri, 06 Feb 2026 13:32:10 +0000

Next.js 15+ da navigatsiya qanday ishlaydi - Prefetching, Streaming, Client-side Transitions, useLinkStatus va History API

Next.js App Router - Linking va Navigatsiya

Next.js da sahifalar serverda renderlanadi. Bu degani - yangi sahifani ko'rsatish uchun client server javobini kutishi kerak. Lekin Next.js buni sezilmas darajada tez qiladi. Qanday? 4 ta texnologiya orqali:

Prefetching - oldindan yuklash
Streaming - oqim sifatida yuborish
Client-side Transitions - client tomonida almashtirish
Loading UI - yuklanish skeletoni

Navigatsiya qanday ishlaydi - 4 ta kalit tushuncha

Foydalanuvchi link bosadi
        │
        ▼
┌──────────────────┐
│  1. PREFETCHING   │  Link viewport ga kirganda oldindan yuklanadi
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  2. SERVER        │  Server Component Payload serverda yaratiladi
│     RENDERING     │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  3. STREAMING     │  Server tayyor qismlarni ketma-ket yuboradi
└────────┬─────────┘
         │
         ▼
┌──────────────────────┐
│  4. CLIENT-SIDE       │  Sahifa to'liq yuklanmasdan, faqat o'zgargan
│     TRANSITION        │  qism almashtiriladi (SPA kabi)
└──────────────────────┘

1. Prefetching - Oldindan yuklash

Foydalanuvchi hali bosmagan sahifani oldindan fonda yuklash. Natijada link bosilganda sahifa deyarli bir zumda ochiladi.

Next.js <Link> komponenti bilan bog'langan sahifalarni avtomatik prefetch qiladi - link viewport ga kirganda yoki hover qilinganda.

import Link from 'next/link';

export default function Nav() {
  return (
    <nav>
      {/* Link - avtomatik prefetch qiladi */}
      <Link href="/blog">Blog</Link>

      {/* Oddiy <a> - prefetch QILMAYDI */}
      <a href="/contact">Kontakt</a>
    </nav>
  );
}

Prefetch route turiga qarab farqlanadi:

Route turi	Prefetch xatti-harakati
Static route (`/about`)	To'liq sahifa oldindan yuklanadi
Dynamic route (`/blog/[slug]`)	`loading.tsx` bo'lsa - layout + skeleton yuklanadi. Bo'lmasa - prefetch o'tkazib yuboriladi

Nima uchun dynamic route to'liq prefetch qilinmaydi? Chunki dynamic sahifalarning ma'lumoti so'rov vaqtida aniqlanadi. Masalan, 10,000 ta blog post bor - hammasini oldindan yuklash mantiqiy emas.

2. Streaming - Ma'lumotni oqim sifatida yuborish

Server butun sahifani tayyorlab bo'lishni kutmasdan, tayyor bo'lgan qismlarni ketma-ket yuboradi:

Oddiy rendering:
Server: [=========== to'liq sahifa tayyor ===========] → Client ga yuborish
                                                         (uzoq kutish)

Streaming bilan:
Server: [Layout tayyor] → yuborish
        [Sidebar tayyor] → yuborish
        [Content tayyor] → yuborish
         ▲ darhol              ▲ tezda           ▲ oxirgi qism

Streaming ni yoqish - `loading.tsx`

// app/dashboard/loading.tsx
export default function Loading() {
  return (
    <div className="animate-pulse">
      <div className="h-8 bg-gray-200 rounded w-1/3 mb-4" />
      <div className="h-4 bg-gray-200 rounded w-full mb-2" />
      <div className="h-4 bg-gray-200 rounded w-2/3 mb-2" />
      <div className="h-4 bg-gray-200 rounded w-1/2" />
    </div>
  );
}

Ichkarida Next.js shunday qiladi:

// Next.js avtomatik ravishda:
<Layout>
  <Suspense fallback={<Loading />}>
    <Page />   {/* Ma'lumot yuklanguncha Loading ko'rsatiladi */}
  </Suspense>
</Layout>

`loading.tsx` ning afzalliklari:

Foydalanuvchi darhol vizual javob oladi (skeleton)
Layout interaktiv bo'lib qoladi (sidebar, nav ishlayveradi)
Navigatsiyani to'xtatish mumkin (boshqa linkni bosish)
Core Web Vitals yaxshilanadi (TTFB, FCP, TTI)

3. Client-side Transitions

An'anaviy server-rendered saytlarda har bir navigatsiya to'liq sahifa yuklanishiga olib keladi - state yo'qoladi, scroll qaytadi, barcha narsa qayta yuklanadi.

Next.js <Link> bilan client-side transition qiladi:

An'anaviy sayt:                    Next.js:
┌──────────────┐                  ┌──────────────┐
│ Header       │ ← qayta yuklanadi│ Header       │ ← O'ZGARMAYDI
│ Sidebar      │ ← qayta yuklanadi│ Sidebar      │ ← O'ZGARMAYDI
│ ┌──────────┐ │                  │ ┌──────────┐ │
│ │ Content  │ │ ← qayta yuklanadi│ │ Content  │ │ ← FAQAT SHU
│ └──────────┘ │                  │ └──────────┘ │   YANGILANADI
│ Footer       │ ← qayta yuklanadi│ Footer       │ ← O'ZGARMAYDI
└──────────────┘                  └──────────────┘

Natijada server-rendered ilova SPA kabi tez ishlaydi.

4. Navigatsiya sekin bo'lishi mumkin bo'lgan holatlar

Muammo 1: Dynamic route da `loading.tsx` yo'q

❌ Yomon - foydalanuvchi kutib turadi:
app/blog/[slug]/
└── page.tsx          # Server javob berguncha bo'sh ekran

✅ Yaxshi - darhol skeleton ko'rsatiladi:
app/blog/[slug]/
├── loading.tsx       # Skeleton darhol ko'rsatiladi
└── page.tsx          # Ma'lumot tayyor bo'lganda almashadi

Muammo 2: `generateStaticParams` yo'q

Agar blog postlarni build vaqtida generatsiya qilish mumkin bo'lsa, generateStaticParams qo'shing:

// app/blog/[slug]/page.tsx

// Build vaqtida barcha postlar uchun statik sahifalar yaratiladi
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts')
    .then(res => res.json());

  return posts.map(post => ({
    slug: post.slug,
  }));
  // Natija: [{ slug: "post-1" }, { slug: "post-2" }, ...]
}

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);
  return <article>{post.title}</article>;
}

Natija: /blog/post-1, /blog/post-2 sahifalar build vaqtida tayyor bo'ladi - serverga so'rov yuborilmaydi, deyarli bir zumda ochiladi.

Muammo 3: Sekin internet

Prefetch tugamasdan foydalanuvchi link bosishi mumkin. useLinkStatus hook bilan darhol vizual feedback bering:

// app/ui/loading-indicator.tsx
'use client';

import { useLinkStatus } from 'next/link';

export default function LoadingIndicator() {
  const { pending } = useLinkStatus();

  return (
    <span
      aria-hidden
      className={`loading-dot ${pending ? 'is-pending' : ''}`}
    />
  );
}

/* 100ms kechikish bilan - tez navigatsiyada ko'rinmaydi */
.loading-dot {
  opacity: 0;
  transition: opacity 0.2s;
}
.loading-dot.is-pending {
  opacity: 1;
  animation: pulse 1s infinite;
  animation-delay: 100ms;
}

5. Prefetch ni boshqarish

Prefetch ni o'chirish

Juda ko'p linklar bo'lganda (masalan, cheksiz scroll jadval) resurslarni tejash uchun:

<Link prefetch={false} href="/blog">
  Blog
</Link>

Faqat hover da prefetch (optimal yondashuv)

Barcha linklarni emas, faqat foydalanuvchi ustiga sichqoncha olib borganda prefetch qilish:

// app/ui/hover-prefetch-link.tsx
'use client';

import Link from 'next/link';
import { useState } from 'react';

export function HoverPrefetchLink({
  href,
  children,
}: {
  href: string;
  children: React.ReactNode;
}) {
  const [active, setActive] = useState(false);

  return (
    <Link
      href={href}
      prefetch={active ? null : false}
      onMouseEnter={() => setActive(true)}
    >
      {children}
    </Link>
  );
}

Qachon qaysi strategiya?

Strategiya	Qachon ishlatish
Default (prefetch={undefined})	Ko'p hollarda - viewport ga kirganda prefetch
`prefetch={false}`	Juda ko'p linklar (infinite scroll, katta jadvallar)
Hover prefetch	O'rtacha ko'p linklar - tezlik + resurs tejash balansi

6. Native History API

Ba'zan URL ni o'zgartirish kerak, lekin sahifani qayta yuklashni xohlamaysiz. Masalan: sort, filter, til almashtirish.

`pushState` - Tarixga yangi yozuv qo'shish

Foydalanuvchi "Orqaga" tugmasi bilan qaytishi mumkin:

// app/ui/sort-products.tsx
'use client';

import { useSearchParams } from 'next/navigation';

export default function SortProducts() {
  const searchParams = useSearchParams();

  function updateSorting(sortOrder: string) {
    const params = new URLSearchParams(searchParams.toString());
    params.set('sort', sortOrder);
    window.history.pushState(null, '', `?${params.toString()}`);
    // URL: /products?sort=asc
    // Sahifa QAYTA YUKLANMAYDI
    // "Orqaga" tugmasi bilan oldingi holatga qaytish mumkin
  }

  return (
    <>
      <button onClick={() => updateSorting('asc')}>
        Arzon → Qimmat
      </button>
      <button onClick={() => updateSorting('desc')}>
        Qimmat → Arzon
      </button>
    </>
  );
}

`replaceState` - Joriy tarix yozuvini almashtirish

Foydalanuvchi "Orqaga" tugmasi bilan qayta olmaydi:

// app/ui/locale-switcher.tsx
'use client';

import { usePathname } from 'next/navigation';

export function LocaleSwitcher() {
  const pathname = usePathname();

  function switchLocale(locale: string) {
    const newPath = `/${locale}${pathname}`;
    window.history.replaceState(null, '', newPath);
    // URL: /uz/about → /en/about
    // Sahifa QAYTA YUKLANMAYDI
    // "Orqaga" tugmasi bilan /uz/about ga qaytib BO'LMAYDI
  }

  return (
    <>
      <button onClick={() => switchLocale('uz')}>O'zbekcha</button>
      <button onClick={() => switchLocale('en')}>English</button>
      <button onClick={() => switchLocale('ru')}>Русский</button>
    </>
  );
}

Muhim: Bu usullar Next.js Router bilan sinxronlashadi - usePathname va useSearchParams avtomatik yangilanadi.

pushState vs replaceState

Metod	"Orqaga" tugmasi	Qachon ishlatish
`pushState`	Oldingi holatga qaytadi	Sort, filter, paginatsiya
`replaceState`	Qaytmaydi	Til almashtirish, redirect

7. Barcha navigatsiya usullari - Qiyoslash

Usul	Turi	Prefetch	Qachon ishlatish
`<Link href="/page">`	Deklarativ	Ha	Asosiy navigatsiya
`useRouter().push()`	Programmatik	Yo'q	Event handler ichida
`useRouter().replace()`	Programmatik	Yo'q	Tarixda iz qoldirmasdan
`useRouter().refresh()`	Programmatik	—	Joriy sahifani yangilash
`history.pushState()`	Native	Yo'q	URL o'zgartirish
`history.replaceState()`	Native	Yo'q	URL almashtirish
`<a href="/page">`	HTML	Yo'q	ISHLATMANG - to'liq yuklaydi

8. To'liq navigatsiya jarayoni

Foydalanuvchi /blog sahifasida. /blog/post-1 ga o'tmoqchi:

1. <Link href="/blog/post-1"> viewport ga kiradi
   └── Prefetch boshlanadi (fonda)
       ├── Static → to'liq sahifa yuklanadi
       └── Dynamic → loading.tsx + layout yuklanadi

2. Foydalanuvchi linkni bosadi
   └── Client-side transition boshlanadi
       ├── Layout SAQLANADI (qayta render yo'q)
       ├── loading.tsx skeleton DARHOL ko'rsatiladi
       └── Server ma'lumotni stream qiladi

3. Server javob tayyor
   └── Skeleton → haqiqiy kontent bilan almashadi
       └── Navigatsiya tugadi!

Xulosa - Asosiy qoidalar

Har doim <Link> ishlatang, <a> emas - prefetching va client-side transition uchun
Dynamic route larga loading.tsx qo'shing - darhol vizual feedback uchun
Imkon bo'lsa generateStaticParams bilan statik sahifalar yarating - eng tez variant
Ko'p linklar bo'lsa prefetch strategiyasini optimallashtiring
URL o'zgartirish uchun pushState/replaceState ishlatang - sahifa yuklanmaydi

Bu maqola Next.js 15+ rasmiy dokumentatsiyasi asosida yozilgan.
(https://www.matkarim.uz)

Next.js - Layoutlar va Sahifalar (Layouts & Pages) To'liq Qo'llanma

MATKARIM MATKARIMOV — Fri, 06 Feb 2026 13:25:23 +0000

Next.js 15+ da sahifalar yaratish, layoutlarni ichma-ich joylashtirish, dinamik routelar, searchParams va Link komponenti

Next.js App Router - Layoutlar va Sahifalar (Layouts & Pages)

Next.js da routing fayl tizimiga asoslangan - papka va fayllar orqali routelar yaratiladi. Bu maqolada sahifalar, layoutlar, dinamik routelar va navigatsiya haqida batafsil tushuntiraman.

1. Sahifa yaratish (Page)

Sahifa - bu ma'lum bir URL da ko'rsatiladigan UI. page.tsx fayl yaratib, default export qilasiz:

app/
└── page.tsx       # / (bosh sahifa)

// app/page.tsx
export default function Page() {
  return <h1>Hello Next.js!</h1>;
}

Qoida: Har doim default export bo'lishi shart. Named export (export const Page) ishlamaydi!

2. Layout yaratish

Layout - bir nechta sahifalar orasida umumiy bo'lgan UI (header, sidebar, footer). Layoutning eng muhim xususiyatlari:

Navigatsiya qilganda qayta renderlanmaydi
State saqlanib qoladi
Interaktiv bo'lib qoladi

// app/layout.tsx - Root Layout (MAJBURIY)
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="uz">
      <body>
        <header>
          <nav>Navigatsiya</nav>
        </header>
        <main>{children}</main>
        <footer>Footer 2026</footer>
      </body>
    </html>
  );
}

children - bu sahifa yoki ichki layout. Foydalanuvchi /about ga o'tsa, children o'rniga app/about/page.tsx renderlanadi.

Muhim qoidalar:

Root layout (app/layout.tsx) majburiy
Unda <html> va <body> teglari bo'lishi shart
Har bir papkada o'zining alohida layout bo'lishi mumkin

3. Ichki (Nested) Routelar yaratish

Papkalarni ichma-ich joylashtirish orqali URL segmentlar hosil bo'ladi:

app/
├── layout.tsx              # Root layout
├── page.tsx                # /
└── blog/
    ├── layout.tsx          # Blog layout
    ├── page.tsx            # /blog
    └── [slug]/
        └── page.tsx        # /blog/my-post

URL segmentlar tushuntirilishi:

/blog/my-post
 │     │    │
 │     │    └── [slug] - Leaf Segment (oxirgi)
 │     └── blog - Segment
 └── / - Root Segment

Amaliy misol - Blog sahifasi:

// app/blog/page.tsx - /blog sahifasi
import Link from 'next/link';
import { getPosts } from '@/lib/posts';

export default async function BlogPage() {
  const posts = await getPosts(); // Server Component - to'g'ridan-to'g'ri API chaqirish

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  );
}

4. Ichki Layoutlar (Nested Layouts)

Layoutlar avtomatik ravishda ichma-ich joylashadi. Har bir papkadagi layout o'z children ini o'rab oladi:

app/
├── layout.tsx          # 1-daraja: Root Layout
├── page.tsx
└── blog/
    ├── layout.tsx      # 2-daraja: Blog Layout
    ├── page.tsx
    └── [slug]/
        └── page.tsx

// app/layout.tsx - Root Layout
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="uz">
      <body>
        <nav>Asosiy Navigatsiya</nav>
        {children}  {/* <-- bu yerga BlogLayout kiradi */}
      </body>
    </html>
  );
}

// app/blog/layout.tsx - Blog Layout
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <section>
      <h2>Blog Bo'limi</h2>
      <aside>Blog Sidebar</aside>
      <div>{children}</div>  {/* <-- bu yerga blog sahifalar kiradi */}
    </section>
  );
}

`/blog/my-post` sahifasi qanday ko'rinadi:

┌─────────────────────────────────────┐
│ Asosiy Navigatsiya (Root Layout)    │
│ ┌─────────────────────────────────┐ │
│ │ Blog Bo'limi (Blog Layout)      │ │
│ │ ┌──────────┐ ┌────────────────┐ │ │
│ │ │ Blog     │ │ Blog Post      │ │ │
│ │ │ Sidebar  │ │ Content        │ │ │
│ │ │          │ │ (page.tsx)     │ │ │
│ │ └──────────┘ └────────────────┘ │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

Muhim farq: Foydalanuvchi /blog/post-1 dan /blog/post-2 ga o'tganda:

Root Layout qayta renderlanmaydi
Blog Layout qayta renderlanmaydi
Faqat page.tsx yangilanadi

Bu juda tez navigatsiya beradi!

5. Dinamik Segmentlar (Dynamic Routes)

Kvadrat qavslar [param] bilan parametrli sahifalar yaratiladi. params prop orqali qiymatni olasiz:

// app/blog/[slug]/page.tsx
export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params; // params - Promise, await qilish kerak!
  const post = await getPost(slug);

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </div>
  );
}

Eslatma: Next.js 15+ da params asinxron bo'ldi, await qilish shart.

URL	`slug` qiymati
`/blog/nextjs-kirish`	`"nextjs-kirish"`
`/blog/react-hooks`	`"react-hooks"`
`/blog/typescript-asoslari`	`"typescript-asoslari"`

6. Search Params bilan ishlash

URL dagi ?key=value parametrlarini o'qish uchun searchParams prop ishlatiladi:

// app/products/page.tsx
// URL: /products?category=electronics&page=2

export default async function ProductsPage({
  searchParams,
}: {
  searchParams: Promise<{
    [key: string]: string | string[] | undefined;
  }>;
}) {
  const { category, page } = await searchParams; // Bu ham Promise!
  // category = "electronics"
  // page = "2"

  const products = await getProducts({
    category,
    page: Number(page),
  });

  return (
    <div>
      <h1>Mahsulotlar: {category}</h1>
      {products.map(p => (
        <div key={p.id}>{p.name}</div>
      ))}
    </div>
  );
}

Qachon nimani ishlatish kerak?

Usul	Qachon ishlatiladi	Misol
`searchParams` prop	Server Component da ma'lumot yuklash uchun	Paginatsiya, filter, qidiruv
`useSearchParams()` hook	Client Component da UI o'zgartirish uchun	Allaqachon yuklangan listni filtrlash
`new URLSearchParams(window.location.search)`	Event handler ichida	Button click da URL ni o'qish (re-render bo'lmaydi)

Client Component misoli:

'use client';
import { useSearchParams } from 'next/navigation';

export function SearchFilter() {
  const searchParams = useSearchParams();
  const category = searchParams.get('category'); // "electronics"

  return <p>Tanlangan kategoriya: {category}</p>;
}

7. Sahifalar orasida navigatsiya - `<Link>`

<Link> komponenti - Next.js da sahifalar orasida o'tish uchun asosiy usul:

import Link from 'next/link';

export default function Navigation() {
  return (
    <nav>
      <Link href="/">Bosh sahifa</Link>
      <Link href="/blog">Blog</Link>
      <Link href="/about">Biz haqimizda</Link>

      {/* Dinamik link */}
      <Link href={`/blog/${post.slug}`}>{post.title}</Link>
    </nav>
  );
}

<Link> ning afzalliklari:

Prefetching - sahifa oldindan yuklab olinadi (viewport ga kirganida)
Client-side navigation - to'liq sahifa yangilanmaydi, faqat o'zgargan qism
Layout saqlanadi - layout qayta renderlanmaydi

Murakkab navigatsiya uchun useRouter hook ishlatiladi:

'use client';
import { useRouter } from 'next/navigation';

export function LogoutButton() {
  const router = useRouter();

  const handleLogout = async () => {
    await logout();
    router.push('/login');      // Sahifaga o'tish
    router.replace('/login');   // Tarixda oldingi sahifa saqlanmaydi
    router.refresh();           // Joriy sahifani yangilash
  };

  return <button onClick={handleLogout}>Chiqish</button>;
}

8. Route Props Helpers (TypeScript)

Next.js 15+ da PageProps va LayoutProps yordamchi tiplar mavjud. Bular import qilmasdan ishlatiladi:

// app/blog/[slug]/page.tsx
export default async function Page(props: PageProps<'/blog/[slug]'>) {
  const { slug } = await props.params;
  return <h1>Blog post: {slug}</h1>;
}

// app/dashboard/layout.tsx
export default function Layout(props: LayoutProps<'/dashboard'>) {
  return <section>{props.children}</section>;
}

Bu tiplar next dev, next build yoki next typegen buyruqlari ishga tushirilganda avtomatik generatsiya qilinadi.

9. To'liq amaliy misol

Keling, hamma narsani birlashtiramiz - oddiy blog loyihasi:

app/
├── layout.tsx              # Root Layout
├── page.tsx                # / (Bosh sahifa)
└── blog/
    ├── layout.tsx          # Blog Layout (sidebar bilan)
    ├── page.tsx            # /blog (postlar ro'yxati)
    └── [slug]/
        └── page.tsx        # /blog/post-nomi (bitta post)

// app/layout.tsx
import Link from 'next/link';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="uz">
      <body>
        <header>
          <nav>
            <Link href="/">Bosh sahifa</Link>
            <Link href="/blog">Blog</Link>
          </nav>
        </header>
        <main>{children}</main>
        <footer>2026 My Blog</footer>
      </body>
    </html>
  );
}

// app/page.tsx
export default function HomePage() {
  return <h1>Blogimga xush kelibsiz!</h1>;
}

// app/blog/layout.tsx
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div style={{ display: 'flex' }}>
      <aside>
        <h3>Kategoriyalar</h3>
        <ul>
          <li>React</li>
          <li>Next.js</li>
          <li>TypeScript</li>
        </ul>
      </aside>
      <section>{children}</section>
    </div>
  );
}

// app/blog/page.tsx
import Link from 'next/link';
import { getPosts } from '@/lib/posts';

export default async function BlogPage() {
  const posts = await getPosts();

  return (
    <div>
      <h1>Barcha postlar</h1>
      <ul>
        {posts.map(post => (
          <li key={post.id}>
            <Link href={`/blog/${post.slug}`}>{post.title}</Link>
          </li>
        ))}
      </ul>
    </div>
  );
}

// app/blog/[slug]/page.tsx
import { getPost } from '@/lib/posts';

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <time>{post.date}</time>
      <p>{post.content}</p>
    </article>
  );
}

Xulosa

Tushuncha	Fayl	Xususiyati
Page	`page.tsx`	`default export`, har bir route uchun alohida
Layout	`layout.tsx`	`children` prop, navigatsiyada qayta renderlanmaydi
Root Layout	`app/layout.tsx`	Majburiy, `<html>` va `<body>` bo'lishi shart
Nested Layout	`app/blog/layout.tsx`	Avtomatik ichma-ich joylashadi
Dynamic Route	`[slug]` papka	`params` orqali qiymat olinadi (Promise!)
Search Params	`searchParams` prop	URL query parametrlarini o'qish
Link	`<Link href="">`	Prefetching + client-side navigation
useRouter	`useRouter()` hook	Programmatik navigatsiya (client only)

Eng muhim esda tutish kerak bo'lgan narsa: Layout bir marta renderlanadi va sahifalar o'zgarganda qayta renderlanmaydi - bu Next.js ning eng kuchli tomonlaridan biri!

Bu maqola Next.js 15+ rasmiy dokumentatsiyasi asosida yozilgan.
(https://www.matkarim.uz)

Next.js App Router - Loyiha Strukturasi (Project Structure) To'liq Qo'llanma

MATKARIM MATKARIMOV — Fri, 06 Feb 2026 13:18:50 +0000

Next.js App Router - Loyiha Strukturasi (Project Structure)

Next.js fayl tizimiga asoslangan routing ishlatadi. Bu degani - papka va fayllarning joylashuvi to'g'ridan-to'g'ri URL manzillarini aniqlaydi. Shu sababli loyihaning strukturasini to'g'ri tushunish juda muhim.

Bu maqolada Next.js loyihasining barcha papkalari, fayllari va routing konventsiyalarini misollar bilan tushuntirib beraman.

1. Yuqori darajadagi papkalar (Top-level Folders)

my-project/
├── app/          # App Router - asosiy routing papkasi
├── public/       # Statik fayllar (rasmlar, shriftlar)
├── src/          # Ixtiyoriy - kodlarni alohida saqlash uchun
└── pages/        # Pages Router (eski usul, app bilan birga ishlatilmaydi)

Papka	Vazifasi
`app/`	App Router - barcha sahifalar, layoutlar va routing shu yerda
`public/`	Statik fayllar. `public/logo.png` → brauzerda `/logo.png`
`src/`	Ixtiyoriy. Kodlarni config fayllaridan ajratish uchun

2. Yuqori darajadagi fayllar (Top-level Files)

my-project/
├── next.config.js        # Next.js sozlamalari
├── package.json          # Paketlar va skriptlar
├── tsconfig.json         # TypeScript sozlamalari
├── .env                  # Environment o'zgaruvchilar
├── .env.local            # Lokal environment
├── .env.development      # Development uchun
├── .env.production       # Production uchun
├── eslint.config.mjs     # ESLint sozlamalari
├── next-env.d.ts         # TypeScript deklaratsiyalar (avtomatik)
└── .gitignore            # Git tomonidan e'tiborga olinmaydigan fayllar

Eslatma: .env fayllari hech qachon git ga qo'shilmasligi kerak!

3. Routing fayllari - ENG MUHIM QISM

Next.js app/ papkasi ichida maxsus nomli fayllarni taniydi. Har birining aniq vazifasi bor:

Fayl	Vazifasi	Qachon ishlatiladi
`page.tsx`	Sahifa	Brauzerda ko'rinadigan sahifa
`layout.tsx`	Layout	Header, sidebar, footer kabi umumiy UI
`loading.tsx`	Yuklanish	Sahifa yuklanayotganda skeleton/spinner
`error.tsx`	Xatolik	Xatolik yuz berganda ko'rsatiladigan UI
`not-found.tsx`	404	Sahifa topilmaganda
`route.ts`	API	Backend API endpoint
`template.tsx`	Template	Har safar qayta renderlanadigan layout
`default.tsx`	Default	Parallel route fallback sahifasi

Amaliy misol:

app/
├── layout.tsx        # Barcha sahifalar uchun umumiy layout
├── page.tsx          # Bosh sahifa: /
├── loading.tsx       # Bosh sahifa yuklanayotganda
├── not-found.tsx     # 404 sahifa
└── error.tsx         # Xatolik sahifasi

// app/layout.tsx - Root Layout
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="uz">
      <body>
        <header>Sayt Sarlavhasi</header>
        <main>{children}</main>
        <footer>Footer</footer>
      </body>
    </html>
  );
}

// app/page.tsx - Bosh sahifa (/)
export default function HomePage() {
  return <h1>Bosh sahifa</h1>;
}

4. Ichki (Nested) Routelar

Papka = URL segment. Papkalarni ichma-ich joylashtirish orqali URL hosil bo'ladi:

app/
├── page.tsx                      # /
├── blog/
│   ├── page.tsx                  # /blog
│   ├── layout.tsx                # Blog sahifalarining umumiy layouti
│   └── authors/
│       └── page.tsx              # /blog/authors
└── about/
    └── page.tsx                  # /about

MUHIM QOIDA

Papka ichida page.tsx yoki route.ts bo'lmasa, u route sifatida ishlamaydi! Shu sababli app/ ichida xavfsiz tarzda komponent va boshqa fayllarni saqlash mumkin:

app/
├── blog/
│   ├── components/        # ❌ Route emas - page.tsx yo'q
│   │   └── PostCard.tsx   # Xavfsiz - brauzerda ochilmaydi
│   └── page.tsx           # ✅ /blog - bu route

5. Dinamik Routelar (Dynamic Routes)

Kvadrat qavslar [] bilan parametrli URL yaratiladi:

app/
├── blog/
│   └── [slug]/
│       └── page.tsx              # /blog/my-first-post
├── shop/
│   └── [...slug]/
│       └── page.tsx              # /shop/clothes, /shop/clothes/shirts
└── docs/
    └── [[...slug]]/
        └── page.tsx              # /docs, /docs/api, /docs/api/hooks

Pattern	Misol URL	Tushuntirish
`[slug]`	`/blog/hello`	Bitta parametr
`[...slug]`	`/shop/a/b/c`	Catch-all - bir nechta segment
`[[...slug]]`	`/docs` yoki `/docs/a/b`	Optional catch-all - bo'sh ham bo'lishi mumkin

// app/blog/[slug]/page.tsx
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>Blog post: {slug}</h1>;
}
// /blog/nextjs-guide → slug = "nextjs-guide"

6. Route Groups - `(papka)` qavslar bilan

URL ga ta'sir qilmasdan papkalarni guruhlab tartibga solish uchun:

app/
├── (marketing)/           # URL da ko'rinmaydi!
│   ├── layout.tsx         # Faqat marketing sahifalari uchun layout
│   ├── page.tsx           # / (bosh sahifa)
│   └── about/
│       └── page.tsx       # /about
├── (shop)/                # URL da ko'rinmaydi!
│   ├── layout.tsx         # Faqat do'kon sahifalari uchun layout
│   ├── cart/
│   │   └── page.tsx       # /cart
│   └── checkout/
│       └── page.tsx       # /checkout
└── layout.tsx             # Root layout

Foydalari:

Saytni bo'limlarga ajratish (marketing, admin, shop)
Har bir guruhga alohida layout berish
Bir nechta root layout yaratish

Bir nechta Root Layout

app/
├── (marketing)/
│   ├── layout.tsx    # <html> va <body> bilan - birinchi root layout
│   └── page.tsx
└── (shop)/
    ├── layout.tsx    # <html> va <body> bilan - ikkinchi root layout
    └── page.tsx

Bu usul bilan marketing va shop butunlay boshqa dizayn ga ega bo'ladi.

7. Private Folders - `_papka` pastki chiziq bilan

Routing tizimidan butunlay chiqarish uchun:

app/
├── blog/
│   ├── _components/       # ❌ Route emas - routing tizimi e'tiborsiz qoldiradi
│   │   ├── PostCard.tsx
│   │   └── CommentList.tsx
│   ├── _lib/              # ❌ Route emas
│   │   └── api.ts
│   └── page.tsx           # ✅ /blog

Foydalari:

UI logikani routing logikadan ajratish
Ichki fayllarni tartibga solish
Kelajakdagi Next.js fayl nomlari bilan to'qnashuvni oldini olish

8. Komponentlar renderlanish tartibi

Next.js maxsus fayllarni qat'iy tartibda ichma-ich joylashtiradi:

<Layout>
  <Template>
    <ErrorBoundary fallback={<Error />}>
      <Suspense fallback={<Loading />}>
        <NotFoundBoundary fallback={<NotFound />}>
          <Page />
        </NotFoundBoundary>
      </Suspense>
    </ErrorBoundary>
  </Template>
</Layout>

Tartib: layout → template → error → loading → not-found → page

9. Metadata fayllari

app/
├── favicon.ico            # Brauzer tab ikonkasi
├── icon.png               # App ikonka
├── apple-icon.png         # Apple qurilmalari uchun
├── opengraph-image.png    # Telegram/Facebook da link ulashganda
├── twitter-image.png      # Twitter uchun
├── sitemap.xml            # SEO - sayt xaritasi
└── robots.txt             # Qidiruv botlari uchun qoidalar

Bularni dinamik ham qilsa bo'ladi:

// app/sitemap.ts
export default function sitemap() {
  return [
    { url: 'https://example.com', lastModified: new Date() },
    { url: 'https://example.com/blog', lastModified: new Date() },
  ];
}

10. Loyihani tartibga solish strategiyalari

Next.js qanday tartib tanlashni sizga qoldiradi. 3 ta mashhur yondashuv:

Strategiya 1: Kod `app` dan tashqarida

project/
├── app/                 # Faqat routing
│   ├── layout.tsx
│   ├── page.tsx
│   └── blog/page.tsx
├── components/          # Barcha komponentlar
├── lib/                 # Utillar, servislar
└── types/               # TypeScript tiplar

Strategiya 2: Hammasi `app` ichida

app/
├── components/
├── lib/
├── layout.tsx
├── page.tsx
└── blog/page.tsx

Strategiya 3: Feature-based (Tavsiya etiladi)

app/
├── components/          # Global komponentlar
├── lib/                 # Global utillar
├── layout.tsx
├── page.tsx
└── blog/
    ├── components/      # Blog-ga tegishli komponentlar
    │   └── PostCard.tsx
    ├── lib/             # Blog-ga tegishli utillar
    │   └── blog-api.ts
    └── page.tsx

11. Parallel va Intercepted Routes

Parallel Routes - `@slot`

Bitta layout ichida bir nechta sahifani parallel ko'rsatish:

app/
├── layout.tsx
├── @analytics/
│   └── page.tsx
├── @team/
│   └── page.tsx
└── page.tsx

// app/layout.tsx
export default function Layout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
}) {
  return (
    <>
      {children}
      {analytics}
      {team}
    </>
  );
}

Intercepted Routes - Modal pattern

app/
├── feed/
│   ├── page.tsx
│   └── (..)photo/[id]/page.tsx   # Modal sifatida ochiladi
└── photo/[id]/
    └── page.tsx                   # To'liq sahifa (direct URL)

Pattern	Ma'nosi
`(.)folder`	Shu darajadagi routeni ushlash
`(..)folder`	Bir daraja yuqoridagi routeni ushlash
`(..)(..)folder`	Ikki daraja yuqoridagi
`(...)folder`	Root dan ushlash

Xulosa

Tushuncha	Belgi	Misol
Oddiy route	papka + `page.tsx`	`app/about/page.tsx` → `/about`
Dinamik route	`[param]`	`app/blog/[slug]/page.tsx`
Route group	`(nom)`	`app/(admin)/...` - URL da ko'rinmaydi
Private folder	`_nom`	`app/_components/` - routing dan chiqariladi
Parallel route	`@slot`	`app/@sidebar/page.tsx`
Intercept	`(.)`, `(..)`, `(...)`	Modal patternlar uchun

Asosiy qoida: Papka ichida page.tsx bo'lmasa, u route emas! Shu sababli app/ ichida xavfsiz tarzda istalgan faylni saqlash mumkin.

Bu maqola Next.js 15+ rasmiy dokumentatsiyasi asosida yozilgan.

(https://www.matkarim.uz)

Building TeamFlow: An AI-Powered Platform for Developer Performance Management

MATKARIM MATKARIMOV — Mon, 02 Feb 2026 10:48:26 +0000

Managing a development team is hard. Tracking performance, analyzing code quality, evaluating skills, and preventing burnout—all while keeping everyone productive—requires more than spreadsheets and gut
feelings.

That's why my colleague Azizbek Matsalayev and I built TeamFlow—an AI-powered smart workspace that transforms how IT teams operate.

## The Problem We Solved

As developers ourselves, we noticed several pain points in IT team management:

No objective performance metrics - Evaluations were subjective
Manual time tracking - Error-prone and often ignored
Code review bottlenecks - No automated quality insights
Burnout blindspots - Managers couldn't see warning signs
Scattered tools - GitHub, Jira, Slack, spreadsheets everywhere

We built TeamFlow to solve all of these with one unified platform.

## What is TeamFlow?

TeamFlow is a comprehensive team management platform that combines:

🤖 AI-Powered Code Analysis - Intelligent agents analyze commits and provide insights
📊 KPI & Performance Tracking - Objective scoring with rankings and grades
⏱️ Smart Time Tracking - Session-based tracking with pause/resume
🔥 Burnout Risk Detection - Early warning system for overworked developers
📈 GitHub Integration - Deep analytics on contributions and code quality
📋 Task Management - Kanban boards and table views with full workflow

## The Tech Stack

We chose a modern, performant stack:

### Frontend
React 19 + TypeScript 5.8
Vite 6.4 (lightning-fast builds)
TanStack Query v5 (server state)
TanStack Table v8 (advanced data grids)
Tailwind CSS v4 + Shadcn/ui
React Hook Form + Zod (type-safe forms)

### Why This Stack?

React 19 - Latest features including improved Suspense
TanStack Query - Eliminated 90% of our state management code
Vite - 10x faster than Create React App
Shadcn/ui - Beautiful, accessible components we own
Zod - Runtime validation that syncs with TypeScript

## Key Features Deep Dive

### 1. AI Agents for Code Analysis

The heart of TeamFlow is our AI Agent system. Managers can create custom AI agents with specific prompts to analyze different aspects of code:


typescript
  // Creating an AI Agent
  interface Agent {
    id: string;
    name: string;           // e.g., "Code Quality Reviewer"
    prompt: string;         // System prompt (up to 10,000 chars)
    description?: string;
  }

  // Agent analyzes commits and generates insights
  interface Analysis {
    id: string;
    project: Project;
    agent: Agent;
    users: User[];
    response: string;       // AI-generated analysis
    dateFrom: string;
    dateTo: string;
    durationSeconds: number;
  }

  How it works:

  1. Select a project and date range
  2. Choose an AI agent (or create a custom one)
  3. Select team members to analyze
  4. AI processes all commits through the agent's prompt
  5. Get comprehensive insights on code quality, patterns, and improvements

  The analysis status flows through: started → get_commits → get_commit_details → analyzing → success

  2. KPI Scoring System

  We built a comprehensive KPI system with multiple scoring categories:

  interface KpiScoring {
    id: string;
    userId: string;
    date: string;
    status: 'draft' | 'completed' | 'locked';
    scores: KpiScoringScore[];
    finalScore?: number;
    grade?: 'A+' | 'A' | 'B+' | 'B' | 'C+' | 'C' | 'D' | 'F';
    rank?: number;
    feedback?: string;
    evaluatedBy?: string;
  }

  Features include:
  - Manual scoring by managers
  - Automatic grade calculation
  - Team rankings
  - Historical performance tracking
  - Admin dashboard with analytics

  3. Smart Time Tracking

  Unlike simple start/stop timers, our time tracking understands developer workflows:

  interface TimeTrackingSession {
    id: string;
    userId: string;
    startedAt: timestamp;
    endedAt?: timestamp;
    pausedAt?: timestamp;
    resumedAt?: timestamp;
    totalDuration: number;      // seconds
    pauseDuration?: number;
    isResearching: boolean;     // Learning vs coding time
  }

  Key features:
  - Pause/Resume - Step away without losing your session
  - Research Mode - Separate learning time from coding time
  - Custom Pause Reasons - Track why work was interrupted
  - Weekly Statistics - Visual breakdown of productive hours

  4. Burnout Risk Detection

  Our dashboard calculates burnout risk based on multiple factors:

  // Dashboard API endpoints
  POST /dashboard/burnout-risk/calculate
  POST /dashboard/day-performance
  POST /dashboard/work-type-comparison  // Remote vs Office
  POST /dashboard/trend-forecast

  The system considers:
  - Overtime patterns
  - Work hours outside normal schedule
  - Consecutive high-intensity days
  - Task completion stress
  - Commit frequency anomalies

  5. GitHub Deep Integration

  We pull comprehensive data from GitHub:

  interface UserStats {
    userId: string;
    projectId: string;
    dateFrom: string;
    dateTo: string;
    totalCommits: number;
    totalAdditions: number;
    totalDeletions: number;
    totalChangedFiles: number;
    fileExtensions: Record<string, number>;  // Lines per language
  }

  This enables:
  - Contribution analytics per developer
  - Code velocity tracking
  - Language distribution insights
  - Commit pattern analysis

  Architecture Highlights

  Feature-Based Structure

  We organized code by feature, not by type:

  src/features/
  ├── ai-agents/          # AI agent CRUD
  ├── analysis/           # AI-powered analysis
  ├── auth/               # JWT authentication
  ├── dashboard/          # KPI analytics
  ├── github-user-stats/  # GitHub integration
  ├── kpi/                # Performance scoring
  ├── projects/           # Repository management
  ├── tasks/              # Task management
  ├── time-tracking/      # Session tracking
  └── users/              # User management

  Each feature contains its own:
  - Components
  - Hooks
  - Services (API calls)
  - Types
  - Validation schemas

  Advanced Data Tables

  Our DataTable component handles enterprise-level data:

  // Features included:
  - Column resizing (drag to resize)
  - Multi-column sorting
  - Advanced filtering
  - Bulk operations
  - Export to Excel/CSV
  - Pagination with URL state
  - Scrollable tooltips for long content

  JWT Authentication Flow

  We implemented automatic token refresh:

  // Axios interceptor for 401/403
  axiosInstance.interceptors.response.use(
    (response) => response,
    async (error) => {
      if (error.response?.status === 401 ||
          error.response?.status === 403) {

        // Remove old token
        removeToken();

        // Try to refresh
        const newToken = await refreshToken();

        if (newToken) {
          // Save and retry request
          saveToken(newToken);
          error.config.headers.Authorization = `Bearer ${newToken}`;
          return axiosInstance(error.config);
        }

        // Refresh failed - redirect to login
        window.location.href = '/auth/login';
      }
      return Promise.reject(error);
    }
  );

  Role-Based Access Control

  Three roles with different permissions:
  ┌─────────────────┬─────────┬───────────────┬─────────────┐
  │     Feature     │  Admin  │    Manager    │  Developer  │
  ├─────────────────┼─────────┼───────────────┼─────────────┤
  │ User Management │ ✅ Full │ ✅ View       │ ❌          │
  ├─────────────────┼─────────┼───────────────┼─────────────┤
  │ AI Agents       │ ✅ Full │ ✅ Full       │ ❌          │
  ├─────────────────┼─────────┼───────────────┼─────────────┤
  │ KPI Scoring     │ ✅ Full │ ✅ Score team │ ✅ View own │
  ├─────────────────┼─────────┼───────────────┼─────────────┤
  │ Projects        │ ✅ Full │ ✅ Full       │ ✅ View     │
  ├─────────────────┼─────────┼───────────────┼─────────────┤
  │ Tasks           │ ✅ Full │ ✅ Full       │ ✅ Assigned │
  ├─────────────────┼─────────┼───────────────┼─────────────┤
  │ Analytics       │ ✅ Full │ ✅ Team       │ ✅ Personal │
  └─────────────────┴─────────┴───────────────┴─────────────┘
  Performance Optimizations

  Code Splitting

  We use manual chunking for optimal loading:

  // vite.config.ts
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor-react': ['react', 'react-dom', 'react-router-dom'],
          'vendor-ui': ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu', ...],
          'vendor-data': ['@tanstack/react-query', '@tanstack/react-table'],
          'vendor-forms': ['react-hook-form', '@hookform/resolvers', 'zod'],
        }
      }
    }
  }

  TanStack Query Caching

  Smart caching reduces API calls:

  const { data: users } = useQuery({
    queryKey: ['users', filters],
    queryFn: () => fetchUsers(filters),
    staleTime: 60 * 1000,        // 1 minute
    gcTime: 5 * 60 * 1000,       // 5 minutes
  });

  Lessons Learned

  1. Feature-based architecture scales better

  Organizing by feature instead of by type (components/, hooks/, etc.) made the codebase much more navigable as it grew.

  2. TanStack Query is a game-changer

  We removed almost all of our Redux code after adopting TanStack Query. Server state and client state are different—treat them differently.

  3. Zod + TypeScript = confidence

  Runtime validation with Zod catches bugs that TypeScript alone misses. Forms especially benefit from this combination.

  4. AI needs good prompts

  Our AI agents are only as good as their system prompts. We spent significant time crafting prompts that give consistent, useful analysis.

  5. Time tracking needs to be frictionless

  If starting/stopping a timer takes more than one click, developers won't use it. We added pause/resume and research mode to match real workflows.

  What's Next?

  We're actively developing:
  - Slack/Discord integration - Notifications where teams already communicate
  - Sprint velocity predictions - AI-powered sprint planning
  - Automated code review suggestions - Beyond just analysis
  - Mobile app - Track time on the go

  Try It Yourself

  TeamFlow is designed for teams of 5-100 developers who want data-driven performance management without the overhead of enterprise tools.

  ---
  About the Authors

  Matkarim Matkarimov - Full Stack Developer
  - Portfolio: https://www.eduzen.uz
  - GitHub: https://github.com/matkarimov099
  - LinkedIn: https://linkedin.com/in/matkarim-matkarimov

  Azizbek Matsalayev - Scala-developer
  - GitHub: https://github.com/matsalayev

  ---
  Have questions about building team management tools or AI integration? Drop a comment below!

  ---

How I Optimized My Portfolio for Google Search: A Complete Next.js SEO Guide

MATKARIM MATKARIMOV — Mon, 02 Feb 2026 10:20:12 +0000

As a Full Stack Developer, I recently rebuilt my portfolio website using Next.js 15 and wanted to ensure it ranks well on Google. In this article, I'll share the complete SEO strategy I implemented,including metadata management, structured data, dynamic OG images, and multilingual support

The Problem

When I searched for my name on Google, my portfolio was nowhere to be found. Instead, other websites with similar names appeared first. I needed a comprehensive SEO strategy to fix this.

## The Solution: A Multi-Layer SEO Approach

### 1. Centralized SEO Configuration

First, I created a centralized configuration file to manage all SEO-related data:


typescript
  // src/lib/seo/config.ts
  export const BASE_URL = "https://www.eduzen.uz";

  export const seoConfig = {
    siteName: "Matkarim Matkarimov",
    author: {
      name: "Matkarim Matkarimov",
      alternateName: "Matkarimov Matkarim",
      jobTitle: "Full Stack Developer",
      email: "matkarimov1099@gmail.com",
    },
    social: {
      github: "https://github.com/matkarimov099",
      linkedin: "https://www.linkedin.com/in/matkarim-matkarimov/",
      telegram: "https://t.me/m_matkarimov",
    },
    keywords: [
      "Matkarimov Matkarim",
      "Full Stack Developer",
      "React Developer",
      "Next.js Developer",
      // ... more keywords
    ],
  } as const;

  2. Reusable Metadata Generator

  Instead of writing metadata manually for each page, I created a reusable function:

  // src/lib/seo/metadata.ts
  import type { Metadata } from "next";

  interface GenerateMetadataOptions {
    title: string;
    description: string;
    path: string;
    locale: Locale;
    type?: "website" | "article" | "profile";
  }

  export function generatePageMetadata({
    title,
    description,
    path,
    locale,
    type = "website",
  }: GenerateMetadataOptions): Metadata {
    const url = `${BASE_URL}/${locale}${path}`;

    // Generate hreflang alternates for all locales
    const languages: Record<string, string> = {};
    for (const loc of locales) {
      languages[loc] = `${BASE_URL}/${loc}${path}`;
    }
    languages["x-default"] = `${BASE_URL}/${defaultLocale}${path}`;

    return {
      title,
      description,
      alternates: {
        canonical: url,
        languages,
      },
      openGraph: {
        title,
        description,
        url,
        siteName: seoConfig.siteName,
        locale: ogLocaleMap[locale],
        type,
      },
      twitter: {
        card: "summary_large_image",
        title,
        description,
      },
      robots: {
        index: true,
        follow: true,
      },
    };
  }

  Now each page only needs a few lines:

  // src/app/[locale]/about/page.tsx
  export async function generateMetadata({ params }: Props): Promise<Metadata> {
    const { locale } = await params;
    const data = seoData[locale as Locale];

    return generatePageMetadata({
      title: data.title,
      description: data.description,
      path: "/about",
      locale: locale as Locale,
      type: "profile",
    });
  }

  3. Dynamic OG Images with next/og

  Static OG images are boring. I created dynamic images that are generated on-the-fly:

  // src/app/opengraph-image.tsx
  import { ImageResponse } from "next/og";

  export const runtime = "edge";
  export const alt = "Matkarimov Matkarim - Full Stack Developer";
  export const size = { width: 1200, height: 630 };
  export const contentType = "image/png";

  export default async function Image() {
    return new ImageResponse(
      (
        <div
          style={{
            height: "100%",
            width: "100%",
            display: "flex",
            flexDirection: "column",
            alignItems: "center",
            justifyContent: "center",
            backgroundColor: "#09090b",
          }}
        >
          <img
            src="https://avatars.githubusercontent.com/matkarimov099"
            alt="Avatar"
            width={150}
            height={150}
            style={{ borderRadius: "50%" }}
          />
          <h1 style={{ color: "white", fontSize: 64 }}>
            Matkarimov Matkarim
          </h1>
          <p style={{ color: "#10b981", fontSize: 32 }}>
            Full Stack Developer
          </p>
        </div>
      ),
      { ...size }
    );
  }

  4. Schema.org Structured Data

  Structured data helps Google understand your content better:

  // src/lib/seo/structured-data.ts
  export function generatePersonSchema() {
    return {
      "@context": "https://schema.org",
      "@type": "Person",
      "@id": `${BASE_URL}/#person`,
      name: "Matkarim Matkarimov",
      alternateName: "Matkarimov Matkarim",
      jobTitle: "Full Stack Developer",
      url: BASE_URL,
      sameAs: [
        "https://github.com/matkarimov099",
        "https://linkedin.com/in/matkarim-matkarimov",
      ],
      knowsAbout: [
        "React", "Next.js", "TypeScript", "Node.js", "PostgreSQL"
      ],
      worksFor: {
        "@type": "Organization",
        name: "UNICON-SOFT",
      },
    };
  }

  Inject it into your layout:

  // src/app/[locale]/layout.tsx
  import { JsonLd } from "@/components/seo";
  import { generatePersonSchema, generateWebSiteSchema } from "@/lib/seo";

  export default function LocaleLayout({ children }) {
    return (
      <>
        <JsonLd data={generatePersonSchema()} />
        <JsonLd data={generateWebSiteSchema()} />
        {children}
      </>
    );
  }

  5. Sitemap and Robots.txt

  Next.js makes this easy with special files:

  // src/app/sitemap.ts
  import type { MetadataRoute } from "next";

  export default function sitemap(): MetadataRoute.Sitemap {
    const pages = ["", "/about", "/projects", "/contact"];
    const locales = ["en", "ru", "uz"];

    return pages.flatMap((page) =>
      locales.map((locale) => ({
        url: `${BASE_URL}/${locale}${page}`,
        lastModified: new Date(),
        changeFrequency: "weekly",
        priority: page === "" ? 1.0 : 0.8,
      }))
    );
  }

  // src/app/robots.ts
  import type { MetadataRoute } from "next";

  export default function robots(): MetadataRoute.Robots {
    return {
      rules: [
        {
          userAgent: "*",
          allow: "/",
          disallow: ["/api/", "/_next/"],
        },
      ],
      sitemap: `${BASE_URL}/sitemap.xml`,
    };
  }

## Results

  After implementing these changes:

  1. ✅ All pages are properly indexed
  2. ✅ Rich snippets appear in search results
  3. ✅ OG images display correctly on social media
  4. ✅ Multilingual support with proper hreflang tags

  Key Takeaways

  1. Centralize your SEO config - Makes maintenance easier
  2. Use dynamic OG images - They're more engaging and always up-to-date
  3. Implement structured data - Helps Google understand your content
  4. Don't forget hreflang - Essential for multilingual sites
  5. Submit to Google Search Console - Speed up indexing

  Check It Out

  You can see all of this in action on my portfolio: https://www.eduzen.uz

  Feel free to connect with me:
  - GitHub: https://github.com/matkarimov099
  - LinkedIn: https://www.linkedin.com/in/matkarim-matkarimov/
  - Telegram: https://t.me/m_matkarimov

  ---
  What SEO strategies do you use for your portfolio? Let me know in the comments!

  ---

DEV Community: MATKARIM MATKARIMOV

Claude Code'ni multi-agent dev jamoaga qanday aylantirdim

Claude Code'ni 12 ta ixtisoslashtirilgan sub-agentga qanday ajratganim

Bitta AI agent bilan muammo

Arxitektura: Sub-agentlar qanday ishlaydi

12 ta agent

Nima uchun turli modellar?

Agent anatomiyasi: Har bir agent faylining ichida nima bor

Chuqur tahlil: Asosiy agentlar

1. senior-dev — Implementatsiya ishchisi

2. code-reviewer — Ikkinchi ko'z

3. debugger — Xato detektivi

4. schema-type-generator — Tiplar va validatsiya

5. git-workflow — Xavfsiz commit qiluvchi

Orkestratsiya oqimi

Umumiy bilim qatlami: coding-rules agent

Sozlash: Konfiguratsiya

Agent fayllari

CLAUDE.md — Loyiha konteksti

Ruxsatlar

Nimalarni o'rgandim

1. Agent descriptionlari routing qoidalari

2. Aniq misollar abstrakt qoidalardan ustun

3. Model tanlovi narx uchun muhim

4. Reviewerlar uchun faqat o'qish vositalari

5. Memory sessiyalar aro o'rganishni yoqadi

Oldin va keyin

O'zingiz sinab ko'ring

How I Turned Claude Code Into a Multi-Agent Dev Team

The Problem With a Single AI Agent

Architecture: How Sub-Agents Work

The 12 Agents

Why Different Models?

Agent Anatomy: What's Inside Each Agent File

Deep Dive: Key Agents

1. senior-dev — The Implementation Workhorse

2. code-reviewer — The Second Pair of Eyes

3. debugger — The Error Detective

4. schema-type-generator — Types and Validation

5. git-workflow — The Safe Committer

The Orchestration Flow

The Shared Knowledge Layer: coding-rules Agent

Setting It Up: Configuration

Agent Files

CLAUDE.md — The Project Context

Permissions

What I've Learned

1. Agent descriptions are routing rules

2. Concrete examples beat abstract rules

3. Model selection matters for cost

4. Read-only tools for reviewers

5. Memory enables cross-session learning

Before and After

Try It Yourself

Feature-Based React Architecture That Actually Scales

Introduction

The Problem with "File-Type" Organization

Feature-Based Architecture — The Core Idea

Full Project Structure

Pattern #1: The Service Layer — API Calls Only

Pattern #2: TanStack Query Hooks with Key Factories

Pattern #3: Zod Schemas with i18n Validation Messages

Pattern #4: Type-Safe Enums Without the enum Keyword

Pattern #5: Responsive Modal — One Component, Two UIs

Pattern #6: Axios Interceptors for Auth

Pattern #7: i18n That Scales to 4+ Languages

Pattern #8: Manual Code Splitting

The Provider Hierarchy

Data Table System

Dark Mode — The Right Way

Terminal-Style Modal Headers

What I'd Do Differently

Key Takeaways

Resources

Next.js App Router - Functions API To'liq Qo'llanma

Next.js App Router - Functions API

Funksiyalar xaritasi

1. cookies() - Cookie bilan ishlash

Cookie o'qish (Server Component)

Cookie yozish (Server Action / Route Handler)

Pattern #4: Type-Safe Enums Without the `enum` Keyword

1. `cookies()` - Cookie bilan ishlash

2. `headers()` - So'rov headerlari

3. `redirect()` va `permanentRedirect()` - Yo'naltirish

`redirect()` - Vaqtinchalik yo'naltirish (307)

`permanentRedirect()` - Doimiy yo'naltirish (308)

4. `notFound()` - 404 sahifa

5. `forbidden()` va `unauthorized()` (Experimental)

6. `useRouter()` - Client-side navigatsiya

`scroll` parametri

7. `usePathname()` - Joriy URL yo'li

8. `useSearchParams()` - URL query parametrlari

9. `useParams()` - Dinamik route parametrlari

10. `useSelectedLayoutSegment()` - Aktiv segment

11. `useLinkStatus()` - Link holati

12. `fetch()` - Kengaytirilgan fetch

`cache` qiymatlari

`next.revalidate` qiymatlari

13. `generateStaticParams()` - Statik sahifalar generatsiyasi

14. `generateMetadata()` - SEO Metadata

`cacheLife()` - Kesh muddati

`cacheTag()` + `revalidateTag()` / `updateTag()`

`revalidatePath()` - Yo'l bo'yicha yangilash

`after()` - Javobdan keyin ishlatish

16. `connection()` - So'rov vaqtiga kechirish

17. `draftMode()` - Qoralama rejim

Client hooklar (`'use client'` da ishlatiladi)

1. `page.tsx` - Sahifa

Client Component da `use()` ishlatish

2. `layout.tsx` - Layout

3. `loading.tsx` - Yuklanish holati

4. `error.tsx` - Xatolik holati

`global-error.tsx` - Root layout xatoliklari uchun

5. `not-found.tsx` - 404 sahifa