هر چه اپلیکیشن React بزرگ‌تر می‌شود، ساختار پوشه‌ها یکی از مهم‌ترین عاملی است که تعیین می‌کند اپلیکیشن تا چه‌قدر قابل نگهداری و مقیاس‌پذیر خواهد بود.

ساختارهای سنتی صافِ مانند components/، pages/ و hooks/ زمانی که کدبیس رشد پیدا می‌کند، بسیار سریع به هم می‌ریزند. در نهایت با صدها فایل نامرتبط در فولدرهای عمومی سروکار دارید — که جستجو، ریفکتور و آنبوردینگ را بسیار دشوار می‌کند.

برای حل این مشکل، معماری فیچر بیس کد را بر اساس دامین یا کارکرد گروه‌بندی می‌کند نه بر اساس نوع فایل. این رویکرد هر فیچر را ایزوله، ماژولار و قابل نگهداری نگاه می‌دارد.

در این مقاله، مفهوم و مزایا را توضیح می‌دهم و — مهم‌تر — یک ساختار فولدر کامل و واقعی که در اپلیکیشن‌های React پروداکشن استفاده می‌کنم را ارائه می‌دهم.

معماری فیچر بیس چیست؟

معماری فیچر بیس یک رویکرد سازمانی است که در آن هرچیزی مرتبط با یک فیچر خاص درون دایرکتوری خودش قرار می‌گیرد.

به جای اینکه تمام کامپوننت‌ها را در components/ و تمام هوک‌ها را در hooks/ قرار دهیم، آن‌ها را بر اساس دامینی که متعلق به آن هستند گروه‌بندی می‌کنیم — برای مثال:

• Auth/
• Menu/
• Branch/
• Setting/

هر فیچر یک ماژول خودمختار می‌شود که شامل:

• کامپوننت‌های UI
• فراخوانی‌های API
• هوک‌ها
• شِماهای اعتبارسنجی
• استورهای state
• روتینگ
• صفحات
• تایپ‌ها

این جداسازی اپلیکیشن‌های بزرگ را قابل‌پیش‌بینی و آسان برای پیمایش می‌کند.

🧩 ساختار سنتی (بر اساس نوع فایل)

src/
├── components/
│   ├── PostItem.tsx
│   ├── PostList.tsx
├── pages/
│   └── PostsPage.tsx
├── hooks/
│   └── usePost.ts
├── types/
│   └── post.types.ts

❌ منطق در فولدرهای عمومی متعدد پخش می‌شود ❌ نگهداری و ریفکتور سخت است ❌ برای اپلیکیشن‌های واقعی مقیاس‌پذیر نیست

✅ نمونهٔ ساختار فیچر بیس

در ادامه یک ساختار واقعی و آماده پروداکشن را می‌بینید — دقیقاً همان ساختاری که در پروژهٔ من استفاده می‌شود.

این ساختار معماری مرکز‌گرا (Core-Oriented) را با یک رویکرد تمیز فیچر بیس ترکیب می‌کند و برای تیم‌های متوسط تا بزرگ و فرانت‌اندهای سطح سازمانی مناسب است.

src/
├── core/
│   ├── assets/         # تصاویر، آیکون‌ها، فونت‌ها و استایل‌های سراسری
│   ├── components/     # کامپوننت‌های UI قابل‌استفادهٔ مجدد و مشترک
│   ├── configs/        # تنظیمات سراسری اپلیکیشن (env، axios، constants)
│   ├── constant/       # ثابت‌های سراسری
│   ├── guard/          # محافظ‌های روت (AuthGuard، RoleGuard)
│   ├── hooks/          # هوک‌های سراسری قابل‌استفادهٔ مجدد
│   ├── layouts/        # کامپوننت‌های لایه‌بندی سراسری (MainLayout، AuthLayout)
│   ├── plugins/        # کتابخانه‌هایی که نیاز به مقدماتی‌سازی دارند (i18n، toast، dayjs)
│   ├── routes/         # تعاریف روتینگ سراسری
│   ├── stores/         # مدیریت state سراسری (Zustand، Redux)
│   ├── types/          # تایپ‌های TypeScript مشترک
│   └── utils/          # توابع کمکی عمومی
│
├── features/
│   ├── Auth/
│   │   ├── api/          # درخواست‌های Auth
│   │   ├── components/   # کامپوننت‌های مخصوص Auth
│   │   ├── hooks/        # هوک‌های مخصوص Auth
│   │   ├── pages/        # صفحات Auth (Login، Register)
│   │   ├── routes/       # روت‌های سطح فیچر
│   │   ├── stores/       # state احراز هویت (tokens، user)
│   │   ├── types/        # تایپ‌های مرتبط با Auth
│   │   └── validation/   # شِماهای فرم
│   │
│   ├── Branch/           # فیچر مدیریت شعبه
│   ├── Menu/             # فیچر مدیریت منو
│   └── Setting/          # فیچر تنظیمات
│
├── App.tsx
├── main.tsx
└── vite-env.d.ts

📌 تفکیک لایه‌ها

۱. core/ — منطق سراسری اپ

هرچیزی که اینجا قرار دارد سراسری است و به یک فیچر خاصی وابسته نیست.

شامل:

• متغیرهای سراسری
• کلاینت‌های axios/http
• providers (احراز هویت، تم، query client)
• لایه‌ها
• هوک‌های مشترک
• محافظ‌های روت
• تنظیمات سراسری
• utils و helpers
• مدیریت state سراسری

اگر چیزی در چند فیچر استفاده می‌شود، جایش در core/ است.

۲. کامپوننت‌های مشترک درون core/components/

این بلوک‌های UI هستند که در هر جای اپلیکیشن قابل استفاده‌اند:

• Button
• Modal
• Input
• Table
• Pagination

آن‌ها به دامین‌ها و فیچرها وابسته نیستند — صرفاً ابزارهای UI هستند.

۳. features/ — قلب معماری

هر فولدر داخل features/ نمایندهٔ یک ماژول دامین کامل است.

هر فیچر تمام آنچه نیاز دارد را شامل می‌شود:

• components → UI مخصوص این فیچر
• hooks → منطق کسب‌وکار
• api → منطق دریافت داده
• pages → نماهای واقعی
• stores → مدیریت state محلی
• types → مدل‌های TypeScript دامین
• validation → شِماهای فرم
• routes → روت‌های متعلق به این فیچر

این باعث می‌شود فیچرها کاملاً ایزوله و آسان برای توسعه، تعویض یا حذف باشند.

۴. ساختار روتینگ

روتینگ شما ترکیبی است:

• core/routes → روتینگ سطح اپلیکیشن
• features/*/routes.ts → روت‌های سطح فیچر

این رویکرد code splitting و lazy loading را بسیار ساده‌تر می‌کند.

چرا این ساختار مؤثر است

✔ مقیاس‌پذیری بالا

به‌خوبی با پروژه‌های بزرگ، صفحات متعدد و ماژول‌های پیچیده کنار می‌آید.

✔ جداسازی واقعی فیچرها

تغییرات داخل یک فیچر معمولاً روی بخش‌های دیگر تأثیری ندارد و ریسک باگ کاهش می‌یابد.

✔ آنبوردینگ سریع‌تر

توسعه‌دهندگان جدید بدون سردرگمی می‌توانند ساختار پروژه را بفهمند و به‌سرعت وارد کار شوند.

✔ الگوی قابل‌پیش‌بینی

تمام فیچرها از یک ساختار یکسان پیروی می‌کنند؛ پیدا کردن فایل‌ها و درک جریان کار ساده‌تر می‌شود.

✔ سازگار با معماری‌های سطح سازمانی

به‌راحتی از الگوهای پیشرفته‌ای مثل Module Federation، Microfrontends و Domain-Driven Design پشتیبانی می‌کند.

نمونهٔ GitHub

این مخزن یک نمونهٔ تمیز از همین معماری را در قالب یک boilerplate ارائه می‌دهد:

naserrasoulii/feature-based-react 👉

می‌توانید آزادانه آن را clone، fork یا حتی در توسعهٔ آن مشارکت کنید.

نتیجه‌گیری

معماری فیچر بیس یکی از مقیاس‌پذیرترین و قابل نگهداری‌ترین روش‌های ساختار‌دهی به اپلیکیشن‌های بزرگ React است. با گروه‌بندی کد بر اساس فیچر به جای نوع فایل — و با پشتیبانی آن توسط یک لایهٔ core تمیز — شما به دست می‌آورید:

• ماژولاریتی
• قابل نگهداری‌بودن
• انعطاف‌پذیری
• ساختار دوست‌دار توسعه‌دهندگان

در نهایت، معماری‌های مختلفی وجود دارد — و هیچ‌کدام بهترین نیست

در دنیای توسعهٔ فرانت‌اند، یک معماری واحد وجود ندارد که برای همهٔ پروژه‌ها بهترین گزینه باشد. انتخاب معماری همیشه به نیازها، مقیاس، تیم، پیچیدگی و محدودیت‌های پروژه بستگی دارد.

آنچه در این مقاله دیدید، صرفاً یکی از رویکردهایی است که من بر اساس تجربهٔ شخصی و شرایط پروژه‌های واقعی انتخاب کرده‌ام.
در بسیاری از پروژه‌ها، این مدل عملکرد فوق‌العاده‌ای داشته، اما ممکن است برای پروژهٔ شما مناسب‌ترین گزینه نباشد و این کاملاً طبیعی است.

معماری درست، معماری‌ای است که مسئلهٔ شما را حل کند.