Kichik React loyihani tashkil qilish: papkalar, nomlar va colocation

Qisqacha: Kichik React loyihada murakkab tuzilma kerak emas: src/ da App.tsx va main.tsx, komponentlar — components/ da (bir fayl — bir komponent, PascalCase.tsx), React'siz sof mantiq — lib/ yoki utils/ da, o'z hooklaringiz — hooks/ da. Loyiha o'sgach, tur bo'yicha (hamma komponentlar bir joyda) tuzilmadan xususiyat bo'yicha (features/menu/, features/cart/) tuzilmaga o'tiladi. Asosiy qoida — colocation: birga o'zgaradigan fayllar birga tursin. Tuzilmani oldindan o'ylab topmang: fayl topish qiyinlashganda o'zgartiring.

Bu darsda

• Kichik React loyihaning odatiy papkalarini va har birining vazifasini bilasiz.
• Tur bo'yicha va xususiyat bo'yicha tuzilmani taqqoslaysiz.
• Colocation qoidasini qo'llaysiz: komponent, uning stili va testi yonma-yon.
• Fayl nomlash odatlarini va Windows'dagi katta-kichik harf tuzog'ini bilasiz.
• Qachon qayta tuzish kerakligini aniqlaysiz.
• vazifalar komponentlarini src/komponentlar/ ga ko'chirasiz — bundle bayt-baytigacha o'zgarmaydi.

Oldin bilishingiz kerak: Komponentlar: yaratish, nomlash va fayllarga ajratish, children va kompozitsiya, Path alias, knip.

1. Nega bu kerak?

vazifalar ning src/ papkasi 16-qism oxirida 22 ta fayl edi. React'ga o'tish davomida komponentlar qo'shildi va hozir u yerda 43 ta fayl bor. Aloqa.tsx yonida amallar.ts, Eksport.tsx yonida fayl.ts, Import.tsx yonida holat.ts. Sardor Statistika ni qidirib, ro'yxatni ikki marta varaqladi. Qaysi fayl React komponenti, qaysi biri sof mantiq — nomidan bilish uchun kengaytmaga (.tsx/.ts) qarash kerak.

Bu xato emas — ilova ishlaydi, testlar o'tadi. Lekin har kuni bir necha soniya yo'qotiladi, yangi kelgan dasturchi esa "nima qayerda?" degan savolga ko'p vaqt sarflaydi. Tuzilma — kod uchun emas, odamlar uchun.

React o'zi papka tuzilmasini talab qilmaydi. Hujjatning eski FAQ bo'limi (legacy.reactjs.org, "File Structure") shunday maslahat bergan edi: loyiha endi boshlanayotgan bo'lsa, tuzilma tanlashga besh daqiqadan ortiq vaqt sarflamang. Keyin, kod o'sgani sari, tuzilmani o'zgartirasiz.

Hayotiy o'xshatish: oshxona javonlari. Kichik uy oshxonasida hamma narsa bitta javonda — qidirmasdan topasiz. Restoran oshxonasida esa bo'limlar bor: ziravorlar, idishlar, xom mahsulot. Lekin bo'limni oldindan emas, javon to'lib, topish qiyinlashganda ajratasiz.

2. Odatiy papkalar

2.1 Vite shablonidan boshlab

Birinchi React loyiha darsida Vite shabloni shunday tuzilma berdi:

src/
  App.tsx
  App.css
  main.tsx
  index.css
  assets/

Kichik loyiha shu bilan boshlanadi. Bir necha komponent paydo bo'lgach, eng keng tarqalgan qadam — ularni alohida papkaga olish:

src/
  main.tsx            ← kirish nuqtasi (createRoot)
  App.tsx             ← ildiz komponent
  components/         ← komponentlar: bir fayl — bir komponent
    MenuCard.tsx
    MenuList.tsx
    CartButton.tsx
  hooks/              ← o'z hooklaringiz: useCart.ts
  lib/                ← React'siz sof funksiyalar: format.ts
  api/                ← server bilan aloqa: menu.ts
  types/              ← umumiy TS turlari: menu.ts
  assets/             ← import qilinadigan rasmlar

main.tsx va App.tsx odatda src/ ildizida qoladi — ular "kirish eshigi", har kim birinchi ochadigan fayllar.

2.2 lib/ ning ahamiyati

lib/ dagi fayllar React'ni bilmaydi: ular oddiy funksiya — massiv oladi, son qaytaradi. Bu ajralish uch foyda beradi:

• test — React, DOM yoki jsdom kerak emas: node --test yetadi (Birinchi avtomatik test);
• qayta ishlatish — server tomonda (Node) ham ishlaydi;
• tushunish — "bu fayl ekranga hech narsa chizmaydi" — nomidan ma'lum.

vazifalar da bu ajralish 12-qismdan beri bor: amallar.ts, qidiruv.ts, saralash.ts, paket.ts — React'siz va node:test bilan sinalgan. React'ga o'tishda ular bitta qator ham o'zgarmagan joylar ko'p — bu ajralishning foydasi.

Tekshirib ko'ring: formatPrice(35000) → "35 000 so'm" qaytaradigan funksiya qaysi papkaga tushadi? usePrice() hook-chi?

3. Tur bo'yicha yoki xususiyat bo'yicha

3.1 Ikki yondashuv

Yuqoridagi tuzilma — tur bo'yicha (by type): hamma komponentlar bir joyda, hamma hooklar boshqa joyda. Loyiha o'sganda boshqa yo'l paydo bo'ladi — xususiyat bo'yicha (by feature): ilovaning har qismi o'z papkasida, ichida o'z komponentlari, hooklari va API'si.

flowchart LR
  subgraph T["Tur bo'yicha"]
    C["components/"] --- C1["MenuCard, CartButton, CartList"]
    H["hooks/"] --- H1["useMenu, useCart"]
    A["api/"] --- A1["menu.ts, cart.ts"]
  end
  subgraph X["Xususiyat bo'yicha"]
    M["features/menu/"] --- M1["MenuCard, useMenu, api"]
    K["features/cart/"] --- K1["CartButton, CartList, useCart, api"]
  end

Chapda "savat" bilan ishlash uchun uch papkani ochasiz. O'ngda — bitta papka.

Ko'p loyihalar ikkalasini aralashtiradi: umumiy kichik komponentlar (Button, Modal) — components/ da, katta qismlar — features/ da. Katta ilova arxitekturasi (chegaralar, qatlamlar) — Katta frontend loyiha arxitekturasi darsida.

3.2 Colocation — birga o'zgaradigan narsalar birga

Colocation ("yonma-yon joylash") — kodni u ishlatiladigan joyga yaqin saqlash. State'ni ko'tarish darsida state uchun ko'rgan edik: state'ni uni ishlatuvchilarga yaqin saqlang. Fayllar uchun ham shu:

components/
  MenuCard/
    MenuCard.tsx
    MenuCard.module.css      ← faqat shu komponent stili
    MenuCard.test.tsx        ← faqat shu komponent testi
    formatDishName.ts        ← faqat MenuCard ishlatadigan yordamchi

MenuCard ni o'zgartirsangiz, odatda stili va testi ham o'zgaradi. Ular yonma-yon bo'lsa — bitta papka. MenuCard ni o'chirsangiz — papkani o'chirasiz, ortida "yetim" CSS qolmaydi. Yordamchi funksiya faqat bitta komponentga kerak bo'lsa, uni umumiy lib/ ga olib chiqish shart emas — faqat ikkinchi joyda kerak bo'lganda.

Testlar alohida papkada (tests/, tekshiruv/) bo'lishi ham to'g'ri yo'l — ayniqsa test sozlamalari (vitest.config.ts dagi include) shunga qurilgan bo'lsa. vazifalar aynan shunday: testlar tekshiruv/ da.

4. Fayl nomlari

4.1 Odatlar

Loyihada bitta odatni tanlang va unga amal qiling. Jamoada bu qaror ko'pincha AGENTS.md, CONTRIBUTING.md yoki linter qoidasida yoziladi.

4.2 index.ts (barrel) fayllari

Ba'zi loyihalarda har papkada index.ts bor — u papkadagi hamma narsani qayta eksport qiladi:

// components/index.ts
export { MenuCard } from "./MenuCard.tsx";
export { CartButton } from "./CartButton.tsx";

// boshqa joyda — bitta import
import { MenuCard, CartButton } from "./components";

Qulay ko'rinadi, lekin narxi bor: barrel fayl import qilinganda uning ichidagi hamma modul yuklanadi. Dev serverda bu sekinlikka, testlarda — ortiqcha modullarga, ba'zan esa aylana importlarga (A → index → B → index → A) olib keladi. Kichik loyihada to'g'ridan-to'g'ri import (./components/MenuCard.tsx) soddaroq va aniqroq. vazifalar da barrel yo'q.

4.3 Windows tuzog'i: katta-kichik harf

State'ni ko'tarish darsida haqiqiy xatoni ko'rdik: Qidiruv.tsx va qidiruv.ts bir papkada. Windows va macOS (sukut bo'yicha) fayl nomida katta-kichik harfni farqlamaydi, Linux esa farqlaydi. Natija — ESLint was not found by the project service dedi. Yana bir xavfli holat: kodda import { MenuCard } from "./menucard.tsx" (kichik harf) — Windows'da ishlaydi, Linux'dagi CI yoki Vercel build'ida esa Could not resolve bilan yiqiladi.

Buni oldindan topadigan kichik tekshiruv yozamiz — fayl yo'llari ro'yxatida faqat harf katta-kichikligi bilan farq qiladigan juftlarni qidiramiz:

function findCaseClashes(paths) {
  const seen = new Map(); // kichik harfli nom → asl yo'l
  const clashes = [];
  for (const path of paths) {
    const key = path.toLowerCase().replace(/\.[^./]+$/, "");
    const other = seen.get(key);
    if (other !== undefined && other !== path) {
      clashes.push([other, path]);
    } else {
      seen.set(key, path);
    }
  }
  return clashes;
}

const files = [
  "src/App.tsx",
  "src/qidiruv.ts",
  "src/Qidiruv.tsx",
  "src/saralash.ts",
  "src/SaralashTanlovi.tsx",
];
console.log(findCaseClashes(files));

Konsolda:

[ [ 'src/qidiruv.ts', 'src/Qidiruv.tsx' ] ]

Kengaytmani olib tashlaymiz, chunki TypeScript ./qidiruv importini .ts ham, .tsx ham deb tushunishi mumkin — aynan shu tufayli ikki fayl to'qnashdi. saralash.ts va SaralashTanlovi.tsx — boshqa nomlar, to'qnashuv yo'q. Bunday tekshiruvni git ls-files natijasiga qo'llab, CI'da ishlatish mumkin.

5. Qachon qayta tuzish kerak

Tuzilma — bir marta tanlanadigan narsa emas. Signallar:

• faylni topish uchun ro'yxatni varaqlaysiz (bitta papkada ~15–20 dan ortiq fayl);
• bitta xususiyatni o'zgartirish uchun 4–5 papkani ochasiz;
• "bu fayl qayerga?" degan savolga jamoada har xil javob;
• import yo'llari ../../../ ga aylangan.

Qayta tuzishning xavfsiz tartibi:

1. Faqat ko'chirish — bitta commit'da faqat fayllar ko'chadi va importlar yangilanadi, mantiq o'zgarmaydi. git mv — Git tarixni fayl bilan birga saqlaydi.
2. Tekshirish — tip tekshiruvi (tsc), testlar, lint va build. Natija bundle avvalgisi bilan bir xil bo'lishi kerak — bu "hech narsa buzilmadi" ning eng kuchli dalili.
3. Ishlatilmagan fayllarni topish — knip: ko'chirishda unutilgan eski fayl yoki eksport.

Muharrir (VS Code) faylni ko'chirganda importlarni o'zi yangilashni taklif qiladi — bu ko'p ishni tejaydi, lekin baribir 2-qadamdagi tekshiruv shart.

5.1 Path alias kerakmi?

../../components/MenuCard.tsx o'rniga @/components/MenuCard.tsx — Path alias darsida ko'rgan usul. Katta loyihada qulay. Lekin u ikki joyda sozlanadi (tsconfig va vite.config.ts). Vite'siz ishlaydigan har vosita (masalan, node --test) uni bilmaydi. vazifalar da alias yo'q — 16-qismda qaror qilingan va sababi bugun ham o'sha: sof mantiq testlari Node'da build'siz ishlaydi, alias ularni buzardi. Kichik loyihada nisbiy yo'l yetadi.

6. Vazifalar qadami: src/komponentlar/

6.1 Reja

Yangi branch: refactor/tuzilma. Faqat ko'chirish:

• 17 ta komponent (.tsx) → src/komponentlar/;
• App.tsx va main.tsx — src/ da qoladi (Vite shablonidagidek);
• sof mantiq (.ts) — src/ da qoladi. Sabab — tekshiruv/*.test.js dagi node:test importlari (../src/amallar.ts) o'zgarmasin, alias yo'q.

Nega components/ emas, komponentlar/? vazifalar da nomlar boshidan o'zbekcha (VazifaRoyxati, holat.ts, amallar.ts) — papka nomi ham shu odatda.

mkdir src/komponentlar
git mv src/Aloqa.tsx src/AmalTugmasi.tsx src/BelgilanganMatn.tsx \
  src/Eksport.tsx src/Filtrlar.tsx src/Import.tsx src/Izoh.tsx \
  src/OchirishDialog.tsx src/OddiyQator.tsx src/Qator.tsx \
  src/QidiruvMaydoni.tsx src/SaralashTanlovi.tsx src/Statistika.tsx \
  src/TahrirQatori.tsx src/VazifaQatori.tsx src/VazifaRoyxati.tsx \
  src/YangiVazifaForma.tsx src/komponentlar/

(git mv muvaffaqiyatli bo'lsa jim tugaydi — chiqish yo'q.) Izoh.tsx ham ko'chdi — endi main.tsx uni ./komponentlar/Izoh.tsx dan import qiladi.

6.2 Importlarni yangilash

Ikki xil o'zgarish. App.tsx da — komponentlar yangi papkada:

-import { Aloqa } from "./Aloqa.tsx";
-import { Eksport } from "./Eksport.tsx";
+import { Aloqa } from "./komponentlar/Aloqa.tsx";
+import { Eksport } from "./komponentlar/Eksport.tsx";

Ko'chgan komponentlar ichida — sof modullar endi bir qavat yuqorida, bir-biriga esa o'sha papkada:

 import { AmalTugmasi } from "./AmalTugmasi.tsx";
 import { BelgilanganMatn } from "./BelgilanganMatn.tsx";
 import { Qator } from "./Qator.tsx";
-import type { QatorAmallari, VazifaMalumoti } from "./turlar.ts";
+import type { QatorAmallari, VazifaMalumoti } from "../turlar.ts";

(OddiyQator.tsx dan.) Testlar (tekshiruv/*.test.tsx) ham komponentlarni import qiladi — ularda ham yo'l yangilanadi. npm run tip ni yangilashlar orasida bir necha marta ishga tushiring: har unutilgan yo'l TS2307: Cannot find module './Aloqa.tsx' or its corresponding type declarations. beradi.

6.3 Natija

Kanondagi src/ (find src -type f | sort, qisqartirilgan):

src/App.tsx
src/amallar.ts
src/api.ts
src/asosiy.ts
…
src/komponentlar/Aloqa.tsx
src/komponentlar/AmalTugmasi.tsx
…
src/komponentlar/YangiVazifaForma.tsx
src/main.tsx
src/marshrut.ts
…
src/vazifa.ts
src/vazifalar.css
src/vite-env.d.ts

Endi bir qarashda ikki dunyo ajralib turibdi: komponentlar/ — React, src/ ildizi — React'siz mantiq va kirish fayllari.

Tekshiruvlar (kanondagi haqiqiy natija):

npm run build && npm test && npm run lint && npm run tip && npx knip

• build: brauzer yuklaydigan JS+CSS — 261 278 bayt, Formalar II dagi holat bilan bayt-baytigacha bir xil. Fayl qayerda turgani bundle'ga ta'sir qilmaydi — Vite hammasini bitta faylga yig'adi.
• testlar: node:test 149/149, Vitest 22/22;
• knip: exit 0 — eski joyda unutilgan fayl yoki eksport yo'q;
• brauzer tekshiruvi: 159/159.

Diff: 23 fayl, +34 −34 — faqat import yo'llari. Commit:

refactor: komponentlar src/komponentlar/ papkasida

PR'ni birlashtiring. Qism oxirida (vazifalar v7 yakuniy holati) src/ da yana ikki papka paydo bo'ladi: hooklar/ (Custom hooklar) va kontekst/ (Context) — tur bo'yicha tuzilmaning davomi.

7. Ko'p uchraydigan xatolar

8. Mashqlar

Mashqlar kurs/mashqlar/17/23-tuzilma/ da.

1-mashq (oson): Qaysi papka?

Tur bo'yicha tuzilmada (components/, hooks/, lib/, api/, types/):

• useOrderTimer.ts:
• calculateTotal.ts (savat jamini hisoblaydi, React'siz):
• fetchMenu.ts (fetch("/api/menu")):
• OrderSummary.tsx:

2-mashq (o'rta): «Bahor» ilovasini xususiyatlarga bo'lish

«Bahor» ilovasining src/ papkasida 14 fayl tekis turibdi: App.tsx, main.tsx, MenuCard.tsx, MenuList.tsx, useMenu.ts, menuApi.ts, CartButton.tsx, CartList.tsx, useCart.ts, cartTotal.ts, BookingForm.tsx, bookingApi.ts, Button.tsx, formatPrice.ts. Ularni xususiyat bo'yicha tuzilmaga joylashtiring: features/menu/, features/cart/, features/booking/, umumiy narsalar uchun components/ va lib/. Har fayl qayerga tushishini yozing.

src/
  main.tsx
  App.tsx
  components/
    Button.tsx            ← hamma xususiyat ishlatadi
  lib/
    formatPrice.ts        ← menyu ham, savat ham ishlatadi
  features/
    menu/
      MenuCard.tsx
      MenuList.tsx
      useMenu.ts
      menuApi.ts
    cart/
      CartButton.tsx
      CartList.tsx
      useCart.ts
      cartTotal.ts        ← faqat savat ishlatadi — colocation
    booking/
      BookingForm.tsx
      bookingApi.ts

3-mashq (qiyin): Tuzilma tekshiruvchisi

«Windows tuzog'i» bo'limidagi findCaseClashes ni kengaytiring: checkStructure(paths) funksiyasi uch xil muammoni topsin va har biri uchun bir qator matn qaytarsin:

1. faqat harf katta-kichikligi bilan farq qiladigan juftlar — "to'qnashuv: A ↔ B";
2. components/ ichidagi, nomi katta harf bilan boshlanmaydigan .tsx fayl — "komponent nomi: …";
3. hooks/ ichidagi, nomi use bilan boshlanmaydigan fayl — "hook nomi: …".

Fayl nomini yo'ldan ajratish: path.split("/").at(-1) (Massivga murojaat).

function checkStructure(paths) {
  const problems = [];
  const seen = new Map();
  for (const path of paths) {
    const key = path.toLowerCase().replace(/\.[^./]+$/, "");
    const other = seen.get(key);
    if (other !== undefined && other !== path) {
      problems.push(`to'qnashuv: ${other} ↔ ${path}`);
    } else {
      seen.set(key, path);
    }
    const name = path.split("/").at(-1);
    if (
      path.includes("/components/") &&
      name.endsWith(".tsx") &&
      !/^[A-Z]/.test(name)
    ) {
      problems.push(`komponent nomi: ${path}`);
    }
    if (path.includes("/hooks/") && !name.startsWith("use")) {
      problems.push(`hook nomi: ${path}`);
    }
  }
  return problems;
}

const files = [
  "src/App.tsx",
  "src/components/MenuCard.tsx",
  "src/components/cartButton.tsx",
  "src/hooks/useCart.ts",
  "src/hooks/cartTimer.ts",
  "src/lib/price.ts",
  "src/lib/Price.tsx",
];
for (const p of checkStructure(files)) console.log(p);

komponent nomi: src/components/cartButton.tsx
hook nomi: src/hooks/cartTimer.ts
to'qnashuv: src/lib/price.ts ↔ src/lib/Price.tsx

4-mashq: Vazifalar qadami

refactor/tuzilma branch'ida «Vazifalar qadami» ni bajaring: 17 ta komponent git mv bilan src/komponentlar/ ga, importlar App.tsx, main.tsx, render.tsx, komponentlar ichida va tekshiruv/*.test.tsx da yangilansin. Build, testlar, lint, tip va knip toza bo'lsin; build hajmi oldingi holat bilan solishtirilsin. Commit va PR.

9. Real ishda

• Yangi ishga kirganda birinchi kunlarda loyihaning tuzilmasini o'qiysiz: src/ da qanday papkalar, komponentlar qayerda, testlar qayerda. Tartibli tuzilma — tez moslashish (Begona repoda orientatsiya).
• Framework'lar tuzilmani belgilaydi: Next.js'da app/ papkasi va fayl nomlari (page.tsx, layout.tsx) marshrutni bildiradi (23-qism). Router kutubxonalarida routes/ (19-qism).
• Kod ko'rigida "bu faylni qayerga qo'ydingiz?" savoli tez-tez chiqadi. Jamoada yozilgan qoida (AGENTS.md, CONTRIBUTING.md) bu bahslarni qisqartiradi.
• Intervyu savollari: "React loyihangizni qanday tuzasiz?", "Feature-based tuzilma nima?", "Colocation nima?", "Barrel fayllarning kamchiligi?".

Xulosa

• Kichik loyiha: main.tsx, App.tsx ildizda; components/, hooks/, lib/ (sof), api/, types/, assets/.
• Tur bo'yicha — kichik va o'rta loyiha uchun; xususiyat bo'yicha — o'sganda; ko'pincha aralash.
• Colocation: birga o'zgaradigan fayllar (komponent, stil, test, yordamchi) birga.
• Nomlar: PascalCase.tsx komponent, useX.ts hook; katta-kichik harf to'qnashuvidan qoching.
• Qayta tuzish: faqat ko'chirish commit'i, keyin tsc + test + build (bundle bir xil) + knip.
• vazifalar: 17 komponent src/komponentlar/ da, sof mantiq src/ da; bundle 261 278 bayt — o'zgarmadi.

Keyingi dars: Amaliy: birinchi to'liq mini-ilova — o'rganilgan hamma narsa bitta ilovada; vazifalar ning butun UI'si React'da, vanilla bilan o'lchangan taqqoslash va Vercel'ga deploy.

Manbalar

• React (legacy docs): "File Structure" FAQ — legacy.reactjs.org/docs/faq-structure.html
• React: "Thinking in React" (komponentlarga bo'lish) — react.dev/learn/thinking-in-react
• Vite: "Project structure" va index.html — vite.dev/guide