A tökéletes mappaszerkezet egy React projekthez

Egy React projekt elindítása izgalmas dolog, de ahogy az alkalmazás növekszik, egyre nehezebbé válhat a kódbázis átláthatósága és kezelhetősége. Ezen a ponton válik létfontosságúvá egy jól átgondolt mappaszerkezet. De létezik-e egyáltalán „tökéletes” szerkezet? A válasz nem egyértelmű igen vagy nem, inkább arról van szó, hogy megtaláljuk azt a megközelítést, amely a legjobban illeszkedik a projektünk méretéhez, csapatunkhoz és a jövőbeli céljaihoz. Ebben a cikkben mélyebben belemerülünk a React mappaszervezésének világába, bemutatjuk a bevált gyakorlatokat, különböző paradigmákat és tippeket adunk, hogyan építhetsz fel egy skálázható és karbantartható alkalmazást.

Miért olyan fontos a mappaszerkezet?

Sokan alábecsülik a projekt mappaszerkezetének jelentőségét, pedig ez az alapja a kódminőségnek és a hosszú távú sikernek. Képzeljünk el egy könyvtárat, ahol a könyvek összevissza, rendszertelenül állnak. Ugyanígy, egy rosszul szervezett kódbázisban nehéz megtalálni a szükséges fájlokat, megérteni a logika működését, vagy hibákat javítani. Egy jól strukturált projekt számos előnnyel jár:

Fejlesztői élmény (DX): A fejlesztők könnyebben navigálnak a kódbázisban, gyorsabban megtalálják a releváns fájlokat, és kevesebb időt töltenek a kereséssel. Ez növeli a hatékonyságot és a morált.
Karbantarthatóság: A moduláris és logikusan elrendezett kód könnyebben karbantartható. A funkciók módosítása vagy bővítése kevésbé jár mellékhatásokkal.
Skálázhatóság: Ahogy a projekt növekszik, az új funkciók hozzáadása egyszerűbbé válik, ha van egy tiszta minta a kód elhelyezésére.
Csapatmunka: Egy egységes szerkezet segít abban, hogy a csapat minden tagja ugyanazt a logikát kövesse, csökkentve a félreértéseket és a kódkonfliktusokat. Az új csapattagok gyorsabban beilleszkednek.
Újrafelhasználhatóság: A jól definiált és izolált komponensek és modulok könnyebben újra felhasználhatók más részeken vagy akár más projektekben is.

Az „optimális” nem „univerzális”: Elvek és megközelítések

Ahogy már említettük, nincs egyetlen, mindenki számára megfelelő „tökéletes” mappaszerkezet. A legjobb megközelítés mindig a projekt egyedi igényeihez igazodik. Vannak azonban alapvető elvek, amelyeket érdemes szem előtt tartani:

Kohézió: A funkcionálisan összefüggő fájlokat tartsuk egy helyen. Például egy adott funkcióhoz tartozó komponenseket, hookokat és stílusokat egy mappában.
Laza kapcsolódás (Loose Coupling): A modulok legyenek minél függetlenebbek egymástól. Ez megkönnyíti a tesztelést, a refaktorálást és az újrafelhasználást.
Skálázhatóság: A szerkezetnek képesnek kell lennie kezelni a projekt növekedését anélkül, hogy káosszá válna.
Olvashatóság és felfedezhetőség: Legyen könnyű megtalálni, amit keresünk, és megérteni, hogy mi hova tartozik.
Konzisztencia: Bármilyen szerkezetet is választunk, tartsuk be következetesen az egész projektben.

Gyakori mappaszerkezeti paradigmák

Két fő megközelítés dominál a React projektek szervezésében, melyeket gyakran kombinálnak is:

1. Típus-vezérelt (By Type / Technical-driven)

Ez a megközelítés a fájlokat a technikai szerepük szerint rendezi. Minden típusú fájl (komponensek, oldalak, hookok, segédprogramok stb.) külön mappába kerül. Ez a legegyszerűbb struktúra, és gyakran az alapértelmezett, amikor egy `create-react-app` projektet indítunk.


src/
├── components/           # Minden újrahasználható komponens
│   ├── Button/
│   ├── Modal/
│   └── Card/
├── pages/                # Oldalak / nézetek
│   ├── HomePage.jsx
│   ├── AboutPage.jsx
│   └── ProductPage.jsx
├── hooks/                # Globális custom hookok
│   ├── useAuth.js
│   └── useDebounce.js
├── utils/                # Segédprogramok és függvények
│   ├── helpers.js
│   └── constants.js
├── assets/               # Képek, ikonok, betűtípusok
├── services/             # API hívások, adatelérési logika
├── store/                # Globális állapotkezelés (Redux, Context)
├── App.js
└── index.js

Előnyök:

Egyszerűség: Kisebb projektek esetén könnyen áttekinthető.
Gyors indulás: Nem igényel sok előzetes tervezést.

Hátrányok:

Alacsony kohézió: Egy funkcióhoz tartozó fájlok szétszóródhatnak a projektben (pl. egy termékoldalhoz tartozó komponensek, hookok, szolgáltatások mind különböző mappákban lennének).
Nehéz skálázhatóság: Nagyobb projekteknél a mappák gyorsan zsúfolttá válnak, és nehéz megtalálni, ami kell.
Nehéz refaktorálás: Egy funkció törlése vagy átnevezése esetén több mappában kell módosításokat végezni.

2. Domain-vezérelt (By Feature / Domain-driven)

Ez a megközelítés a fájlokat az általuk képviselt üzleti logika vagy funkció (domain) szerint rendezi. Minden egyes funkció vagy domain (pl. „autentikáció”, „termékek”, „felhasználói profil”) saját mappát kap, és azon belül található meg minden, ami ehhez a funkcióhoz tartozik (komponensek, hookok, szolgáltatások, stílusok, tesztek).


src/
├── features/               # Fő üzleti funkciók
│   ├── auth/               # Autentikációval kapcsolatos összes kód
│   │   ├── components/     # Lokális komponensek
│   │   │   ├── LoginForm.jsx
│   │   │   └── RegisterForm.jsx
│   │   ├── hooks/          # Lokális hookok
│   │   │   └── useAuthUser.js
│   │   ├── services/       # Lokális szolgáltatások (pl. auth API)
│   │   │   └── authService.js
│   │   ├── pages/          # Autentikációs oldalak
│   │   │   ├── LoginPage.jsx
│   │   │   └── SignupPage.jsx
│   │   └── authSlice.js    # Redux slice vagy Context
│   │
│   ├── products/           # Termékekkel kapcsolatos összes kód
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── pages/
│   │   └── productSlice.js
│   │
│   └── userProfile/        # Felhasználói profil
│       ├── components/
│       ├── hooks/
│       └── UserProfilePage.jsx
│
├── App.js
└── index.js

Előnyök:

Magas kohézió: Minden, ami egy funkcióhoz tartozik, egy helyen van.
Kiváló skálázhatóság: Új funkció hozzáadása egyszerűen egy új mappa létrehozását jelenti.
Egyszerű refaktorálás és törlés: Egy funkció eltávolítása csak a hozzá tartozó mappa törlését jelenti.
Függetlenség: A funkciók önálló modulokként működhetnek, csökkentve a globális függőségeket.
Könnyű tesztelhetőség: Egy funkció tesztelésekor minden releváns fájl könnyen elérhető.

Hátrányok:

Globális komponensek elhelyezése: Azon komponensek, amelyek több funkcióban is felhasználhatók (pl. egy `Button` vagy `Modal`), külön kezelést igényelnek.
Nagyobb kezdeti tervezés: Megköveteli az alkalmazás funkcióinak előzetes felmérését.

Hibrid megközelítés és a javasolt szerkezet

A legtöbb közepes és nagy React alkalmazás a két fenti megközelítés hibridjét alkalmazza. A domain-vezérelt szerkezet adja az alapot a fő üzleti logikának, míg a típus-vezérelt megközelítés bizonyos, globálisan újrahasznosítható elemek számára fenntartott mappákat biztosít. Ez a megközelítés maximalizálja a skálázhatóságot és a karbantarthatóságot, miközben fenntartja az átláthatóságot.

Íme egy részletes javaslat egy hibrid mappaszerkezetre:


src/
├── assets/                 # Statikus erőforrások: képek, ikonok, betűtípusok
│   ├── images/
│   ├── icons/
│   └── fonts/
│
├── components/             # Globálisan újrahasználható "dumb" UI komponensek
│                           # Ezek a komponensek nem tartalmaznak üzleti logikát,
│                           # csak propokat fogadnak és UI-t renderelnek.
│   ├── Button/
│   │   ├── Button.jsx
│   │   ├── Button.module.css (vagy .scss)
│   │   └── index.js        # Exportálja a Button-t
│   ├── Modal/
│   │   ├── Modal.jsx
│   │   ├── Modal.test.js
│   │   └── index.js
│   └── Input/
│
├── features/               # Az alkalmazás fő üzleti funkciói (domain-vezérelt)
│                           # Minden funkció egy önálló modul, saját komponensekkel,
│                           # hookokkal, szolgáltatásokkal, stb.
│   ├── auth/
│   │   ├── components/     # Auth-specifikus komponensek (pl. LoginForm)
│   │   ├── hooks/          # Auth-specifikus hookok (pl. useAuth)
│   │   ├── pages/          # Auth oldalak (pl. LoginPage)
│   │   ├── services/       # Auth API hívások
│   │   ├── store/          # Auth Redux slice / Context
│   │   ├── types/          # Auth TypeScript típusok
│   │   └── index.js        # Exportálja a modul elemeit
│   │
│   ├── products/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── pages/
│   │   ├── services/
│   │   ├── store/
│   │   └── types/
│   │
│   └── userProfile/
│       ├── components/
│       ├── hooks/
│       ├── pages/
│       ├── services/
│       ├── store/
│       └── types/
│
├── hooks/                  # Globálisan újrahasználható custom hookok
│                           # Olyan hookok, amelyek nem tartoznak szigorúan egy funkcióhoz
│   ├── useLocalStorage.js
│   └── useDebounce.js
│
├── lib/                    # Harmadik féltől származó integrációk, complex utils
│                           # (pl. Stripe integráció, Firebase config)
│   ├── firebase.js
│   └── analytics.js
│
├── services/               # Globális API kliensek, vagy olyan szolgáltatások,
│                           # amelyek több funkciót is érintenek
│   ├── api.js              # Axios instace, API kliens
│   └── logger.js
│
├── store/                  # Globális állapotkezelés (Redux store konfiguráció, fő reducers)
│   ├── index.js
│   └── rootReducer.js
│
├── styles/                 # Globális stílusok, témák, változók
│   ├── base.css
│   ├── theme.js
│   └── variables.css
│
├── types/                  # Globális TypeScript típusok és interfészek
│   ├── user.ts
│   └── product.ts
│
├── utils/                  # Egyszerű segédprogramok, konstansok
│   ├── formatters.js
│   └── validators.js
│
├── routes/                 # Az alkalmazás útvonalainak definíciója
│   ├── AppRoutes.jsx
│   └── PublicRoutes.jsx
│
├── App.jsx                 # Fő alkalmazás komponens (routing, layout)
├── main.jsx                # Belépési pont (korábban index.js)
└── reportWebVitals.js

Az Atomic Design elvei a mappaszerkezetben

Brad Frost Atomic Design koncepciója nagyszerűen kiegészítheti a domain-vezérelt struktúrát, különösen a components/ mappán belül. Az Atomic Design lényege, hogy a felhasználói felületet atomokból, molekulákból, organizmusokból, template-ekből és oldalakból építjük fel.

Atomok: Az UI legkisebb, önálló építőkövei (pl. Button, Input, Label). Ezek általában a components/atoms/ mappába kerülnek.
Molekulák: Atomok csoportjai, amelyek együtt alkotnak egy funkcionális egységet (pl. SearchForm: Input + Button). Ezek a components/molecules/ mappába.
Organizmusok: Molekulák és/vagy atomok csoportjai, amelyek komplexebb, mégis önálló UI szekciókat alkotnak (pl. Header, ProductCard). Ezek a components/organisms/ mappába.
Template-ek: Oldalak huzatai, amelyek elrendezéseket definiálnak, de még nem tartalmaznak konkrét adatokat. Ezek a components/templates/ mappába.
Oldalak: A template-ek konkrét adatokkal feltöltött változatai, amelyek a felhasználó által látható felületet alkotják. Ezek általában a features/<featureName>/pages/ mappákban helyezkednek el.

Ez a további rétegződés rendkívül hasznos a nagy, egységes UI könyvtárakkal rendelkező projektekben, vagy ha Storybookot használunk a komponensek dokumentálására.

Fontos szempontok és tippek

Konvenciók és elnevezések

Nagybetűs komponensnevek (PascalCase): Pl. Button.jsx, LoginPage.jsx.
Kisbetűs fájlnevek (camelCase vagy kebab-case): Pl. useAuth.js, auth-service.js.
Mappák esetén kebab-case: Pl. user-profile/.
index.js fájlok: Egy mappa gyökerében lévő index.js fájl exportálhatja az adott mappa fő elemeit, így egyszerűbbé válik az importálás: import { Button } from '@/components/Button'; helyett import Button from '@/components/Button'; vagy import { Button } from '@/components'; ha az index.js gyűjtőexportot tartalmaz.

Aliaszok használata

Konfiguráld a modul aliasokat (pl. Webpack/Vite aliasok vagy TypeScript paths opciója) a gyökér src mappa eléréséhez. Ez elkerüli a hosszú, relatív import útvonalakat (../../../components/Button helyett @/components/Button vagy @src/components/Button).

Példa `jsconfig.json` (JavaScript esetén) vagy `tsconfig.json` (TypeScript esetén):


{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Ezután importálhatsz így: import Button from '@/components/Button';

Tesztfájlok elhelyezése

A tesztfájlokat célszerű a tesztelt fájl mellett elhelyezni (pl. Button.jsx mellett Button.test.js vagy Button.spec.js). Ez növeli a kohéziót és megkönnyíti a tesztek megtalálását.

Stílusfájlok

Használhatsz CSS Modules-t (Button.module.css), Styled Components-et vagy más CSS-in-JS megoldásokat, vagy hagyományos CSS/Sass fájlokat. A lényeg, hogy a stílusfájl is a komponens mellett legyen, ha az adott komponensre specifikus.

Ne feledkezz meg a `.gitkeep` fájlokról!

Ha van üres mappád, amit szeretnél a Git-ben tartani, hozz létre benne egy üres .gitkeep fájlt.

Refaktorálás, ha szükséges

Ne próbáld meg rögtön az elején a „tökéletes” szerkezetet megalkotni, különösen egy kis projekt esetén. Kezdj egy egyszerűbb szerkezettel, és légy hajlandó refaktorálni, ahogy a projekt növekszik és a követelmények tisztázódnak. A mappaszerkezet sem kőbe vésett, alkalmazkodnia kell az alkalmazás fejlődéséhez.

Mikor térj el a szabályoktól?

A fenti irányelvek segítenek a legtöbb esetben, de mindig vannak kivételek. Például:

Nagyon kicsi projektek: Egy demó alkalmazás vagy egy egyszerű landing page esetén a típus-vezérelt szerkezet is elegendő lehet, vagy akár minden egy mappában.
Specifikus keretrendszerek vagy könyvtárak: Egyes eszközök, mint például a Next.js, sajátos mappaelnevezési konvenciókat használnak (pl. pages/ a routinghoz). Ezeket érdemes követni.
Csapat preferenciája: Ha a csapat már megszokott egy bizonyos szerkezetet, és az jól működik számukra, érdemes lehet ahhoz tartani magunkat a konzisztencia és a fejlesztői élmény érdekében.

Összefoglalás

A tökéletes mappaszerkezet egy React projekthez nem egy merev szabályrendszer, hanem egy rugalmas keret, amely a skálázhatóságot, karbantarthatóságot és a kiváló fejlesztői élményt szolgálja. Az alapos tervezés, a domain-vezérelt megközelítés kombinálása a globálisan újrahasznosítható elemek típus-vezérelt elrendezésével, valamint a következetes elnevezési konvenciók és a modul aliasok használata mind hozzájárulnak egy tiszta, átlátható és könnyen kezelhető kódbázishoz.

Emlékezz: a legjobb struktúra az, amely a te projektjeid és csapatod számára a leglogikusabb és leginkább támogatja a hatékony munkát. Ne félj kísérletezni, és alakítsd ki a saját bevált gyakorlataidat a bemutatott elvek és minták alapján. Egy jól szervezett React alkalmazás nemcsak a jelenlegi fejlesztésben segít, hanem megkönnyíti a jövőbeli bővítéseket és a csapat együttműködését is.