تنظیمات ساختاری، ابزارهای مدیریت بسته (Package Managers) و متغیرهای محیطی همگی در بالاترین سطح از دایرکتوری پروژه قرار میگیرند.
app/: ساختار نوین App Router؛ مبنای اصلی مسیردهی، کامپوننتها و منطق برنامه.
pages/: ساختار قدیمی Pages Router (در صورت مهاجرت تدریجی یا استفاده از الگوهای سنتی).
public/: دایرکتوری داراییهای استاتیک (Static Assets) مانند تصاویر، فونتها و فایلهای سیستمی مروگر.
src/: پوشه اختیاری جهت همجوار کردن کدهای اصلی برنامه و تفکیک آنها از فایلهای کانفیگ ریشه.
این فایلها وظیفه پیکربندی فریمورک، مدیریت وابستگیها، ابزارهای نظارتی (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 برای تایپاسکریپت | نباید ردیابی شود (خودکار) |
در درون پوشه 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).
ساختار فولدرها در Next.js بخشهای آدرس اینترنتی (URL Segments) را تعریف میکند. لایهها در هر سطح، فرزندان خود را در آغوش میگیرند.
| ساختار پوشه در پروژه | الگوی آدرس اینترنتی (URL Pattern) | وضعیت دسترسی |
app/layout.tsx | — | لایه ریشه؛ کل برنامه را پوشش میدهد |
app/page.tsx | / | صفحه اصلی وبسایت (عمومی) |
app/blog/layout.tsx | — | لایه مشترک منحصربهفرد برای پوشه وبلاگ و زیرمجموعهها |
app/blog/page.tsx | /blog | صفحه اصلی بخش وبلاگ (عمومی) |
app/blog/authors/page.tsx | /blog/authors | صفحه نویسندگان وبلاگ (عمومی) |
برای متغیر کردن یک پارامتر در آدرس وب، نام پوشه را داخل براکت قرار میدهیم و مقادیر را از طریق ویژگی 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) باز هم صفحه را رندر میکند.
گاهی هدف از ایجاد پوشه، تغییر در آدرس سایت نیست، بلکه صرفاً بهینهسازی ساختار پوشهها و دستهبندی فایلهای پروژه است.
قرار دادن نام پوشه داخل پرانتز ( ) باعث میشود نام آن دایرکتوری از آدرس URL حذف شود. این ابزار برای اعمال لایههای مشترک متفاوت روی صفحات مختلف بدون دستکاری آدرسها کاربرد دارد.
فایل app/(marketing)/page.tsx $\rightarrow$ در آدرس / در دسترس است.
فایل app/(shop)/cart/page.tsx $\rightarrow$ در آدرس /cart در دسترس است.
قرار دادن علامت آندراسکور _ قبل از نام پوشه، آن دایرکتوری را به طور کامل از چرخه سیستم مسیردهی خارج میکند (Private Folder). این فضا مکانی امن برای قرار دادن کامپوننتهای فرعی، ابزارهای کمکی (Utils) یا کدهای تست است.
فایل app/blog/_components/Post.tsx $\rightarrow$ کاملاً خصوصی و غیرقابل دسترسی از طریق آدرس مرورگر.
این دو قابلیت برای ساخت ساختارهای پیشرفته کاربری مانند داشبوردهای چندبخشی یا باز کردن صفحات به صورت ماژولار (Modal) بدون تغییر آدرس اصلی استفاده میشوند.
با استفاده از علامت @folder شیارهای نامگذاری شده (Named Slots) ایجاد میکنید که میتوانند به عنوان ورودیهای مستقل (Props) به لایه مشترک والد ارسال شده و به صورت همزمان رندر شوند (مانند قرار دادن داشبورد آماری و منو در کنار هم).
این الگو به شما اجازه میدهد تا در حین حضور در یک ساختار، صفحه دیگری را در داخل لایه فعلی رندر کنید، بدون اینکه کاربر به آدرس جدید منتقل شود (مثلاً باز کردن پیشنمایش یک تصویر به صورت پاپآپ بر روی لیست تصاویر).
| الگوی رهگیری | مفهوم و کارکرد | نمونه کاربرد عملی |
(.)folder | رهگیری مسیر همسطح (همان دایرکتوری) | باز کردن پاپآپ پیشنمایش در کنار لیست |
(..)folder | رهگیری مسیر یک سطح بالاتر (والد) | باز کردن فرزند والد به عنوان یک لایه رویی |
(..)(..)folder | رهگیری مسیر دو سطح بالاتر | دسترسی به ساختارهای عمیقتر در فایلسیستم |
(...)folder | رهگیری مسیر از ریشه پوشه app | نمایش یک آدرس دلخواه کل سایت در ویوی فعلی |
Next.js نام فایلهای زیر را به عنوان استانداردهای فراداده و سئو شناسایی کرده و تگهای متناظر با آنها را در بخش <head> کدهای HTML خروجی تزریق میکند. شما میتوانید این فایلها را به صورت استاتیک قرار دهید یا به صورت دینامیک (با پسوندهای برنامهنویسی جاوااسکریپت) رندر کنید.
favicon.ico: فایل اصلی آیکون وبسایت در لبه مروگر.
icon.ico / .png / .svg: فایل نماد برنامه (App Icon).
icon.js / .ts: تولید پویا و داینامیک نماد برنامه با کدنویسی.
apple-icon.png: فایل بهینهسازی شده برای نماد دستگاههای شرکت اپل.
opengraph-image.png / .jpg: تصویر پیشنمایش هنگام اشتراکگذاری آدرس سایت در پلتفرمهای اجتماعی (مانند تلگرام، لینکدین و...).
opengraph-image.ts: ساخت هوشمند و داینامیک تصاویر اشتراکگذاری گرافیکی بر اساس اطلاعات هر صفحه.
twitter-image.png: تصویر بهینهسازی شده اختصاصی برای کارتهای پلتفرم توییتر (X).
sitemap.xml / sitemap.js: نقشه سایت جهت راهنمایی رباتهای موتورهای جستجو (گوگل).
robots.txt / robots.js: فایل دسترسیها و محدودیتهای خزش برای رباتهای وب.
این محتوا کاملا رایگان توسط تیم کدلپر ترجمه شده و در اختیار شما کاربران عزیز قرار گرفته است، هر گونه کپی برداری برای مقاصد غیر رایگان و بدون ذکر منبع، مورد پیگیری قانونی قرار میگیرد.
ترجمه شده از منبع: https://nextjs.org/docs/app