ویرگول
ورودثبت نام
پدرام رمضان زاده
پدرام رمضان زاده
پدرام رمضان زاده
پدرام رمضان زاده
خواندن ۶ دقیقه·۲ ماه پیش

توسعه یک پنل حرفه‌ای با Next.js؛ از ساختار پروژه تا مدیریت دسترسی

این نوشته حاصل تجربهای است که هنگام توسعه و تکمیل یک پنل تحت وب با Next.js به دست آوردم. در طول کار، با موضوعاتی مثل ساختاردهی پروژه، اضافه کردن سطح دسترسی جدید، مدیریت Routeها، طراحی Sidebar، کار با فرمها، ارتباط با API و حتی بعضی خطاهای رایج Next.js روبهرو شدم.

تصمیم گرفتم بخشی از این تجربه را بهصورت ساده و آموزشی بنویسم؛ بدون ورود به جزئیات یک پروژه خاص، تا این مطالب برای کسانی که روی پروژههای مشابه کار میکنند هم قابل استفاده باشد.

هدف این نیست که یک معماری پیچیده و ایدهآل معرفی کنم؛ بیشتر قرار است درباره چند نکته کاربردی صحبت کنیم که در پروژههای واقعی فرانتاند زیاد با آنها مواجه میشویم.

اگر با Next.js، TypeScript و App Router کار میکنید یا قصد دارید یک پنل چندسطحی طراحی کنید، احتمالاً بخش زیادی از این تجربهها برایتان آشنا یا مفید خواهد بود.


1. چرا ساختار پروژه اهمیت دارد؟

یکی از اولین مشکلاتی که در پروژههای بزرگ فرانتاند ایجاد میشود، پراکندگی فایلهاست.

برای مثال فرض کنید نرمافزار چند نوع کاربر دارد:

  • کاربر عادی

  • کارشناس

  • مدیر سیستم

هرکدام از این کاربران ممکن است صفحات و منوهای متفاوتی داشته باشند، اما در عین حال بخشهایی مانند Header، Sidebar یا سیستم نمایش پیامها بین آنها مشترک باشد.

در Next.js App Router میتوان با استفاده از Route Groupها ساختار این بخشها را از یکدیگر جدا کرد.

یک ساختار ساده میتواند به شکل زیر باشد:

src/ └── app/ ├── (user-panel)/ │ ├── layout.tsx │ └── dashboard/ │ ├── (expert-panel)/ │ ├── layout.tsx │ ├── requests/ │ └── profile/ │ └── (admin-panel)/ ├── layout.tsx └── dashboard/

پرانتز در App Router باعث میشود بتوانیم مسیرهای پروژه را از نظر ساختاری دستهبندی کنیم، بدون اینکه الزاماً نام آن گروه در URL نمایش داده شود.

2. استفاده از Layout برای جلوگیری از تکرار

معمولاً صفحات یک پنل اجزای مشترکی دارند؛ برای مثال:

Sidebar Header Main Content Notifications

بهجای اینکه این اجزا را در تکتک صفحات قرار دهیم، میتوانیم یک layout.tsx برای پنل ایجاد کنیم.

یک نمونه ساده:

export default function PanelLayout({ children, }: { children: React.ReactNode; }) { return ( <div className="flex"> <Sidebar /> <main className="flex-1"> {children} </main> </div> ); }

به این ترتیب تمام صفحات داخل این Route Group بهصورت خودکار Layout مشترک را دریافت میکنند.

این روش هم کد را تمیزتر میکند و هم تغییرات آینده را سادهتر خواهد کرد.

3. ساخت Sidebar براساس سطح دسترسی

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

بهتر است اطلاعات منو از خود کامپوننت Sidebar جدا باشد.

برای مثال:

const menuItems = [ { title: "داشبورد", href: "/dashboard", }, { title: "درخواستها", href: "/requests", }, { title: "پروفایل", href: "/profile", }, ];

سپس Sidebar فقط وظیفه نمایش این اطلاعات را بر عهده داشته باشد.

در پروژههای بزرگتر حتی میتوان برای هر نقش مجموعه منوی جداگانه تعریف کرد:

const menus = { user: [...], expert: [...], admin: [...], };

با این روش اضافه کردن یک Role جدید به سیستم سادهتر میشود.

4. مراقب تداخل Routeها باشید

یکی از نکات مهم Route Groupهای Next.js این است که نام داخل پرانتز بخشی از URL محسوب نمیشود.

برای مثال:

(user-panel)/profile/page.tsx

و:

(expert-panel)/profile/page.tsx

ممکن است هر دو به مسیر زیر تبدیل شوند:

/profile

در نتیجه Next.js نمیتواند تشخیص دهد کدام صفحه باید نمایش داده شود.

این موضوع میتواند خطایی مشابه زیر ایجاد کند:

You cannot have two parallel pages that resolve to the same path

بنابراین هنگام طراحی ساختار Routeها باید علاوه بر ساختار پوشهها، URL نهایی صفحات را نیز در نظر گرفت.

5. اهمیت Export و Import صحیح کامپوننتها

یکی دیگر از خطاهای متداول React و Next.js زمانی اتفاق میافتد که default export و named export اشتباه استفاده شوند.

اگر کامپوننت به شکل زیر تعریف شده باشد:

export default function Sidebar() { return <aside>...</aside>; }

باید آن را به این شکل Import کنیم:

import Sidebar from "./Sidebar";

اما اگر بنویسیم:

export function Sidebar() { return <aside>...</aside>; }

Import صحیح آن خواهد بود:

import { Sidebar } from "./Sidebar";

اشتباه در این قسمت میتواند باعث خطاهایی مانند Element type is invalid شود.

6. مدیریت فرمهای بزرگ با react-hook-form

در پنلهای واقعی معمولاً فرمها بخش مهمی از پروژه هستند.

استفاده مستقیم از تعداد زیادی useState برای مدیریت فرمهای بزرگ، کد را پیچیده میکند.

یکی از راهکارهای مناسب استفاده از react-hook-form است.

نمونه ساده:

const { register, handleSubmit, watch, } = useForm(); const = (data: FormValues) => { console.log(data); };

سپس میتوان ورودیها را ثبت کرد:

<input {...register("amount")} />

یکی از قابلیتهای کاربردی watch این است که میتوان تغییر مقادیر فرم را قبل از Submit مشاهده کرد.

7. نمایش Preview قبل از ثبت اطلاعات

در بسیاری از فرمهای مالی، سفارش، رزرو یا درخواست خدمات بهتر است کاربر قبل از ثبت نهایی نتیجه انتخابهایش را مشاهده کند.

برای مثال کاربر ممکن است مقداری وارد کند و سیستم قبل از Submit اطلاعاتی مانند موارد زیر را محاسبه کند:

مبلغ انتخابشده مدت قرارداد تعداد پرداختها نرخ محاسباتی مبلغ هر پرداخت جدول پرداخت

در این حالت جریان رابط کاربری بهتر است به شکل زیر باشد:

ورود اطلاعات ↓ اعتبارسنجی ↓ محاسبه Preview ↓ نمایش نتیجه ↓ تأیید کاربر ↓ ارسال درخواست

این طراحی احتمال ثبت اطلاعات اشتباه را کاهش میدهد و تجربه کاربری بهتری ایجاد میکند.

8. TypeScript Typeها را از UI جدا کنید

اگر API دادهای مانند زیر برگرداند:

{ "amount": 100000, "duration": 12, "installments": 12 }

بهتر است Type مربوط به آن جدا تعریف شود:

export type CalculationResult = { amount: number; duration: number; installments: number; };

سپس در کامپوننت:

const [result, setResult] = useState<CalculationResult | null>(null);

این کار چند مزیت دارد:

  • خطاهای برنامهنویسی زودتر مشخص میشوند.

  • ساختار داده API واضحتر میشود.

  • تغییر API راحتتر قابل مدیریت است.

  • قابلیت Auto Complete محیط توسعه بهتر میشود.

9. کامپوننتها را بیدلیل زیاد نکنید

Component-based بودن React به این معنی نیست که هر چند خط کد باید به یک فایل جدا تبدیل شود.

برای مثال اگر یک صفحه دارای فرم و یک بخش Preview کوچک است، الزاماً نیازی نیست دهها فایل برای آن ساخته شود.

تفکیک زمانی ارزشمند است که کامپوننت:

  • در چند محل استفاده شود،

  • مسئولیت مشخص و مستقلی داشته باشد،

  • بیش از حد بزرگ شده باشد،

  • یا تست و نگهداری جداگانه آن مفید باشد.

هدف اصلی باید خوانایی و نگهداری بهتر کد باشد، نه صرفاً افزایش تعداد کامپوننتها.

10. ارتباط Frontend و API

یک اصل مهم در توسعه فرانتاند این است که منطق تجاری حساس نباید صرفاً در مرورگر پیادهسازی شود.

برای مثال در یک محاسبه مهم، Frontend میتواند اطلاعات را از کاربر دریافت کند، اما نتیجه معتبر بهتر است توسط Backend محاسبه یا تأیید شود.

جریان کلی میتواند چنین باشد:

Frontend ↓ User Input ↓ API Request ↓ Backend Validation ↓ Business Logic ↓ API Response ↓ Preview ↓ Final Confirmation

این تفکیک باعث میشود مسئولیت Frontend و Backend مشخصتر باشد.

11. نقش Nginx در استقرار پروژه

در محیط توسعه معمولاً برنامه مستقیماً روی یک Port اجرا میشود:

localhost:3000

اما در محیط Production معمولاً کاربر نباید شماره Port داخلی برنامه را بداند.

اینجاست که Reverse Proxyهایی مانند Nginx کاربرد پیدا میکنند.

ساختار کلی میتواند چنین باشد:

User ↓ Domain ↓ Nginx ↓ Next.js Application

Nginx درخواستهای ورودی روی پورتهای استاندارد وب را دریافت کرده و آنها را به Port داخلی برنامه هدایت میکند.

علاوه بر Reverse Proxy، میتوان از آن برای مواردی مانند SSL termination، تنظیم Headerها، محدودسازی درخواستها و مدیریت چند سرویس روی یک سرور نیز استفاده کرد.

ساختار مناسب Routeها، استفاده صحیح از Layout، مدیریت Roleها، طراحی Sidebar، TypeScript، مدیریت فرمها، ارتباط صحیح با API و معماری مناسب استقرار همگی در کیفیت نهایی پروژه تأثیر دارند.

اگر بخواهم این تجربه را در یک جمله خلاصه کنم:

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

یک معماری ساده و قابل نگهداری میتواند در آینده زمان زیادی برای توسعه، رفع باگ و اضافه کردن قابلیتهای جدید ذخیره کند.

gt ltfrontjs
۰
۰
پدرام رمضان زاده
پدرام رمضان زاده
شاید از این پست‌ها خوشتان بیاید