ساختار route
فایل page.tsx یک مسیر را قابلدسترسی میکند و layout پوستهٔ مشترک میسازد.
app/ layout.tsx page.tsx about/ page.tsx blog/ [slug]/ page.tsx
مرجع مسیرها، رندر صفحه، metadata و دریافت داده در App Router. App Router از ساختار فایل در app مسیر میسازد. صفحهها و layoutها بهطور پیشفرض Server Component هستند؛ راهنمای این بخش بر مبنای مستندات نسخهٔ جاری Next.js نوشته شده است. مرز client را تا حد نیاز کوچک نگه دارید. state، event handler و API مرورگر به Client Component نیاز دارند؛ دسترسی امن سمت سرور در Server Component باقی بماند. از این صفحه بهعنوان مرجع سریع استفاده کنید و مثالها و نکتهها را با نسخهٔ ابزار، نیاز و شرایط واقعی پروژهٔ خود تطبیق دهید.
فایل page.tsx یک مسیر را قابلدسترسی میکند و layout پوستهٔ مشترک میسازد.
app/ layout.tsx page.tsx about/ page.tsx blog/ [slug]/ page.tsxlayout فرزند را در children قرار میدهد و در ناوبری state مشترک را حفظ میکند.
export default function RootLayout({ children,}: Readonly<{ children: React.ReactNode }>) { return ( <html lang="fa" dir="rtl"> <body>{children}</body> </html> );}در Next.js جدید params ناهمگام است؛ مقدار مسیر را await و سپس ورودی را اعتبارسنجی کنید.
export default async function Page({ params,}: { params: Promise<{ slug: string }>;}) { const { slug } = await params; return <h1>{slug}</h1>;}برای انتقال داخلی از Link استفاده کنید تا رفتار ناوبری Next حفظ شود.
import Link from "next/link";export default function Home() { return <Link href="/about">دربارهٔ ما</Link>;}directive باید پیش از importها و در ابتدای فایل باشد.
"use client";import { useState } from "react";export function Counter() { const [count, setCount] = useState(0); return <button onClick={() => setCount(count + 1)}>{count}</button>;}داده را نزدیک منبع در سمت سرور دریافت کنید.
export default async function Page() { const response = await fetch("https://api.example.test/posts"); if (!response.ok) throw new Error("Unable to load posts"); const posts = await response.json(); return <PostList posts={posts} />;}کدهای وابسته به window یا localStorage را در مرز Client Component قرار دهید.
Server Component:- داده و secrets سمت سرور- کاهش JavaScript مرورگرClient Component:- state و event handler- APIهای window و documentکد وضعیت HTTP را بررسی کنید؛ fetch برای پاسخ 4xx/5xx خودکار reject نمیشود.
const response = await fetch(apiUrl);if (!response.ok) { throw new Error(`Request failed: ${response.status}`);}const data = await response.json();metadata را در layout/page صادر کنید یا برای مسیر پویا تولید کنید.
import type { Metadata } from "next";export const metadata: Metadata = { title: "راهنما", description: "مستندات کاربردی",};route.ts از Web Request/Response و متدهای HTTP نامدار استفاده میکند.
export async function GET() { return Response.json({ status: "ok" });}export async function POST(request: Request) { const body = await request.json(); return Response.json({ received: Boolean(body) }, { status: 201 });}برای مسیرهای پویا که هنگام build شناخته شدهاند generateStaticParams صادر کنید.
export async function generateStaticParams() { const posts = await getPosts(); return posts.map((post) => ({ slug: post.slug }));}ساختار مسیرها را با پوشههای app و فایلهای page و layout تعریف کنید.
کامپوننت سرور را پیشفرض نگه دارید و فقط برای تعامل مرورگر use client اضافه کنید.
پارامترهای مسیر پویا را در پوشهای مانند [slug] دریافت و اعتبارسنجی کنید.
داده را در سرور نزدیک به منبع بخوانید و حالتهای loading و خطا را در نظر بگیرید.
عنوان و توضیحات صفحه را با metadata یا generateMetadata تنظیم کنید.
برای مسیرهای قابل پیشساخت از generateStaticParams استفاده کنید.
برای ناوبری داخلی از Link استفاده کنید و مسیر قدیمی را با redirect نگه دارید.
تصاویر و فونتها را با توجه به شیوهٔ مستند و سازگار نسخهٔ پروژه مدیریت کنید.
مرزهای cache و تازگی داده را متناسب با صفحه مشخص کنید.
پیش از انتشار، مسیر مستقیم، refresh، metadata و رفتار production را آزمایش کنید.
Route Handler را برای endpointهای app تعریف و پاسخ، روش HTTP و اعتبارسنجی ورودی را صریح کنترل کنید.
در نسخهٔ پروژه APIهای cache و پارامترهای route را با مستندات همان نسخه تطبیق دهید؛ مثالهای نسخههای قدیمی را عیناً منتقل نکنید.