قراردادهای فایل ها و پوشه ها

۱. پوشه‌ها و فایل‌های ریشه پروژه (Top-Level Structure)

تنظیمات ساختاری، ابزارهای مدیریت بسته (Package Managers) و متغیرهای محیطی همگی در بالاترین سطح از دایرکتوری پروژه قرار می‌گیرند.

پوشه‌های ریشه (Top-Level Folders)

• app/: ساختار نوین App Router؛ مبنای اصلی مسیردهی، کامپوننت‌ها و منطق برنامه.

• pages/: ساختار قدیمی Pages Router (در صورت مهاجرت تدریجی یا استفاده از الگوهای سنتی).

• public/: دایرکتوری دارایی‌های استاتیک (Static Assets) مانند تصاویر، فونت‌ها و فایل‌های سیستمی مروگر.

• src/: پوشه اختیاری جهت هم‌جوار کردن کدهای اصلی برنامه و تفکیک آن‌ها از فایل‌های کانفیگ ریشه.

فایل‌های کانفیگ ریشه (Top-Level Files)

این فایل‌ها وظیفه پیکربندی فریم‌ورک، مدیریت وابستگی‌ها، ابزارهای نظارتی (Monitoring) و متغیرهای حساس را بر عهده دارند:

نام فایل	قلمرو و کارکرد	وضعیت ردیابی در گیت (Git)
next.config.js	فایل اصلی پیکربندی و تنظیمات اختصاصی Next.js	باید ردیابی شود
package.json	مدیریت پکیج‌ها، وابستگی‌ها (Dependencies) و اسکریپت‌های اجرایی	باید ردیابی شود
tsconfig.json / jsconfig.json	تنظیمات کامپایلر کامپوننت‌های TypeScript یا JavaScript	باید ردیابی شود
eslint.config.mjs	فایل قوانین پیکربندی ابزار خطایابی ساختاری ESLint	باید ردیابی شود
instrumentation.ts	تنظیمات مربوط به ابزارهای مانیتورینگ سیستم و OpenTelemetry	باید ردیابی شود
proxy.ts	پلتفرم مدیریت و هدایت درخواست‌ها (Request Proxy)	باید ردیابی شود
.gitignore	دستورات نادیده‌گرفتن فایل‌ها در سامانه کنترل نسخه گیت	باید ردیابی شود
.env	متغیرهای محیطی عمومی سیستم	نباید ردیابی شود (مخفی)
.env.local	متغیرهای محیطی محلی و مخصوص سیستم توسعه‌دهنده	نباید ردیابی شود (مخفی)
.env.development	متغیرهای محیطی مخصوص محیط توسعه و کدنویسی	معمولاً ردیابی می‌شود
.env.production	متغیرهای محیطی مخصوص محیط عملیاتی و نهایی	معمولاً ردیابی می‌شود
next-env.d.ts	فایل تعاریف نوع اختصاصی Next.js برای تایپ‌اسکریپت	نباید ردیابی شود (خودکار)

۲. فایل‌های سیستم مسیردهی (Routing Files)

در درون پوشه app، وجود فایل‌های استاندارد زیر نوع رابط کاربری (UI) و نقاط دسترسی شبکه (API Endpoints) را پایه‌ریزی می‌کند. پسوندهای قابل استفاده برای فایل‌های بخش کلاینت شامل .js ، .jsx و .tsx است.

• page.tsx: سازنده اصلی یک صفحه (Page). وجود این فایل برای تبدیل یک پوشه به آدرس عمومی الزامی است.

• layout.tsx: ساختار لایه مشترک (Layout). المان‌های پایداری مثل هدر (Header) یا فوتر (Footer) را مدیریت کرده و در جابه‌جایی بین مسیرهای هم‌سطح مجدداً رندر نمی‌شود.

• template.tsx: مشابه قالب لایه مشترک است، با این تفاوت که با هر تغییر مسیر، یک نمونه جدید از آن رندر می‌شود (Re-rendered Layout).

• loading.tsx: لایه نمایش وضعیت بارگذاری تعاملی (Skeleton UI) مبتنی بر قابلیت استریم کدهای سرور.

• error.tsx: تعریف محدوده مجزای خطا (Error Boundary) جهت به دام انداختن خطاهای ناگهانی ران‌تایم.

• global-error.tsx: لایه پیشرفته مدیریت خطاهای ریشه که کل برنامه (حتی لایه ریشه layout.tsx) را پوشش می‌دهد.

• not-found.tsx: رابط کاربری اختصاصی برای خطای یافت نشدن صفحه (Status Code 404).

• route.ts: تعریف فایل مستقل برای پاسخگویی به درخواست‌های شبکه در سمت سرور (API Endpoint).

• default.js: صفحه پشتیبان (Fallback) برای بخش‌های موازی سیستم مسیردهی (Parallel Routes).

۳. معماری مسیرهای تو در تو و پویا (Nested & Dynamic Routes)

ساختار فولدرها در Next.js بخش‌های آدرس اینترنتی (URL Segments) را تعریف می‌کند. لایه‌ها در هر سطح، فرزندان خود را در آغوش می‌گیرند.

مسیرهای تو در تو (Nested Routes)

ساختار پوشه در پروژه	الگوی آدرس اینترنتی (URL Pattern)	وضعیت دسترسی
app/layout.tsx	—	لایه ریشه؛ کل برنامه را پوشش می‌دهد
app/page.tsx	/	صفحه اصلی وب‌سایت (عمومی)
app/blog/layout.tsx	—	لایه مشترک منحصربه‌فرد برای پوشه وبلاگ و زیرمجموعه‌ها
app/blog/page.tsx	/blog	صفحه اصلی بخش وبلاگ (عمومی)
app/blog/authors/page.tsx	/blog/authors	صفحه نویسندگان وبلاگ (عمومی)

مسیرهای پویا (Dynamic Routes)

برای متغیر کردن یک پارامتر در آدرس وب، نام پوشه را داخل براکت قرار می‌دهیم و مقادیر را از طریق ویژگی params در کد دریافت می‌کنیم:

• پارامتر تک‌بخشی [segment]: مانند app/blog/[slug]/page.tsx که آدرس /blog/my-first-post را باز می‌کند.

• پارامترهای چندبخشی فرگیر [...segment]: مانند app/shop/[...slug]/page.tsx که تمام زیرمسیرهای مابعد خود را شامل می‌شود (مانند /shop/clothing و /shop/clothing/shirts).

• پارامترهای فرگیر اختیاری [[...segment]]: مانند app/docs/[[...slug]]/page.tsx که حتی اگر هیچ پارامتری بعد از آن ارسال نشود (مانند آدرس خاکی /docs) باز هم صفحه را رندر می‌کند.

۴. گروه‌بندی مسیرها و پوشه‌های خصوصی

گاهی هدف از ایجاد پوشه، تغییر در آدرس سایت نیست، بلکه صرفاً بهینه‌سازی ساختار پوشه‌ها و دسته‌بندی فایل‌های پروژه است.

گروه‌های مسیر (Route Groups)

قرار دادن نام پوشه داخل پرانتز ( ) باعث می‌شود نام آن دایرکتوری از آدرس URL حذف شود. این ابزار برای اعمال لایه‌های مشترک متفاوت روی صفحات مختلف بدون دستکاری آدرس‌ها کاربرد دارد.

• فایل app/(marketing)/page.tsx $\rightarrow$ در آدرس / در دسترس است.

• فایل app/(shop)/cart/page.tsx $\rightarrow$ در آدرس /cart در دسترس است.

پوشه‌های خصوصی (Private Folders)

قرار دادن علامت آندراسکور _ قبل از نام پوشه، آن دایرکتوری را به طور کامل از چرخه سیستم مسیردهی خارج می‌کند (Private Folder). این فضا مکانی امن برای قرار دادن کامپوننت‌های فرعی، ابزارهای کمکی (Utils) یا کدهای تست است.

• فایل app/blog/_components/Post.tsx $\rightarrow$ کاملاً خصوصی و غیرقابل دسترسی از طریق آدرس مرورگر.

۵. مسیرهای موازی و رهگیری‌شده (Parallel & Intercepted Routes)

این دو قابلیت برای ساخت ساختارهای پیشرفته کاربری مانند داشبوردهای چندبخشی یا باز کردن صفحات به صورت ماژولار (Modal) بدون تغییر آدرس اصلی استفاده می‌شوند.

مسیرهای موازی (Parallel Routes)

با استفاده از علامت @folder شیارهای نام‌گذاری شده (Named Slots) ایجاد می‌کنید که می‌توانند به عنوان ورودی‌های مستقل (Props) به لایه مشترک والد ارسال شده و به صورت همزمان رندر شوند (مانند قرار دادن داشبورد آماری و منو در کنار هم).

مسیرهای رهگیری‌شده (Intercepted Routes)

این الگو به شما اجازه می‌دهد تا در حین حضور در یک ساختار، صفحه دیگری را در داخل لایه فعلی رندر کنید، بدون اینکه کاربر به آدرس جدید منتقل شود (مثلاً باز کردن پیش‌نمایش یک تصویر به صورت پاپ‌آپ بر روی لیست تصاویر).

الگوی رهگیری	مفهوم و کارکرد	نمونه کاربرد عملی
(.)folder	رهگیری مسیر هم‌سطح (همان دایرکتوری)	باز کردن پاپ‌آپ پیش‌نمایش در کنار لیست
(..)folder	رهگیری مسیر یک سطح بالاتر (والد)	باز کردن فرزند والد به عنوان یک لایه رویی
(..)(..)folder	رهگیری مسیر دو سطح بالاتر	دسترسی به ساختارهای عمیق‌تر در فایل‌سیستم
(...)folder	رهگیری مسیر از ریشه پوشه app	نمایش یک آدرس دلخواه کل سایت در ویوی فعلی

۶. قراردادهای مربوط به فایل‌های سئو (SEO) و دارایی‌های فراداده (Metadata)

Next.js نام فایل‌های زیر را به عنوان استانداردهای فراداده و سئو شناسایی کرده و تگ‌های متناظر با آن‌ها را در بخش <head> کدهای HTML خروجی تزریق می‌کند. شما می‌توانید این فایل‌ها را به صورت استاتیک قرار دهید یا به صورت دینامیک (با پسوندهای برنامه‌نویسی جاوااسکریپت) رندر کنید.

تصاویر و آیکون‌های برنامه (App Icons & Images)

• favicon.ico: فایل اصلی آیکون وب‌سایت در لبه مروگر.

• icon.ico / .png / .svg: فایل نماد برنامه (App Icon).

• icon.js / .ts: تولید پویا و داینامیک نماد برنامه با کدنویسی.

• apple-icon.png: فایل بهینه‌سازی شده برای نماد دستگاه‌های شرکت اپل.

تصاویر اشتراک‌گذاری اجتماعی (Open Graph & Twitter)

• opengraph-image.png / .jpg: تصویر پیش‌نمایش هنگام اشتراک‌گذاری آدرس سایت در پلتفرم‌های اجتماعی (مانند تلگرام، لینکدین و...).

• opengraph-image.ts: ساخت هوشمند و داینامیک تصاویر اشتراک‌گذاری گرافیکی بر اساس اطلاعات هر صفحه.

• twitter-image.png: تصویر بهینه‌سازی شده اختصاصی برای کارت‌های پلتفرم توییتر (X).

فایل‌های بهینه‌سازی موتورهای جستجو (SEO Tools)

• sitemap.xml / sitemap.js: نقشه سایت جهت راهنمایی ربات‌های موتورهای جستجو (گوگل).

• robots.txt / robots.js: فایل دسترسی‌ها و محدودیت‌های خزش برای ربات‌های وب.