ساخت پروژه با create-next-app

در این درس اولین پروژه‌ی Next.js 16 را می‌سازیم. این پروژه همان DevNotes است که در تمام دوره روی آن کار می‌کنیم. برای ساخت آن از ابزار رسمی create-next-app استفاده می‌کنیم؛ ابزاری که پوشه‌ی پروژه، فایل‌های پیکربندی و وابستگی‌ها را برای ما آماده می‌کند.

پیش‌نیاز

درس CH01-S03: نصب Node.js (نسخه‌ی 20.9 یا بالاتر)، npm و ویرایشگر کد
اتصال به اینترنت، چون ابزار باید بسته‌ها را دانلود کند

create-next-app چیست؟

create-next-app یک ابزار خط فرمان (CLI) است که چند سؤال از شما می‌پرسد و بر اساس پاسخ‌ها، یک پروژه‌ی آماده می‌سازد. نیازی به نصب جداگانه ندارد؛ با دستور npx که همراه npm نصب می‌شود، مستقیماً اجرا می‌شود. عبارت @latest یعنی آخرین نسخه‌ی این ابزار استفاده شود.

گام ۱: اجرای دستور ساخت پروژه

ترمینال را در پوشه‌ای باز کنید که می‌خواهید پروژه‌ها را در آن نگه دارید (مثلاً یک پوشه‌ی projects) و این دستور را اجرا کنید:

bash

npx create-next-app@latest devnotes

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

گام ۲: پاسخ به سؤال‌ها

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

text

Would you like to use the recommended Next.js defaults?
    Yes, use recommended defaults
    No, reuse previous settings
    No, customize settings

نکته‌ی مهم: تنظیمات پیشنهادی Cache Components را روشن می‌کند

طبق مستندات رسمی (آخرین به‌روزرسانی مشاهده‌شده: اکتبر ۲۰۲۶)، تنظیمات پیشنهادیِ فعلی شامل Cache Components است؛ یعنی گزینه‌ی cacheComponents در پروژه‌ی ساخته‌شده روشن می‌شود. این گزینه رفتار کش و رندر را تغییر می‌دهد و در فصل ۷ کامل بررسی می‌شود.

ما در فصل‌های ۲ تا ۶ می‌خواهیم رفتار پایه‌ی Next.js را بدون این گزینه یاد بگیریم و در CH07-S05 آن را آگاهانه روشن کنیم و تفاوت را ببینیم. به همین دلیل در این دوره گزینه‌ی No, customize settings را انتخاب می‌کنیم.

پاسخ‌های ما در حالت customize

سؤال	پاسخ ما	دلیل
`Would you like to use TypeScript?`	Yes	تمام کدهای دوره با TypeScript نوشته می‌شوند.
`Which linter would you like to use?`	ESLint	خطاها و الگوهای ناامن کد را بررسی می‌کند (فصل ۱۱).
`Would you like to use React Compiler?`	No	در `CH15-S04` به‌صورت جداگانه بررسی می‌شود.
`Would you like to use Tailwind CSS?`	Yes	در فصل ۱۱ از آن در حد کاربردی استفاده می‌کنیم.
`Would you like your code inside a src/ directory?`	No	پوشه‌ی `app` مستقیماً در ریشه‌ی پروژه می‌ماند تا مسیرها در درس‌ها ساده باشند.
`Would you like to use App Router? (recommended)`	Yes	کل دوره روی App Router است.
`Would you like to use Cache Components?`	No	در فصل ۷ و در زمان مناسب فعال می‌شود.
`Would you like to customize the import alias (@/* by default)?`	No	همان `@/*` را نگه می‌داریم.
`Would you like to include AGENTS.md ...?`	No	این فایل راهنمای ابزارهای کدنویسی هوشمند است و برای این دوره لازم نیست.

نام و ترتیب سؤال‌ها ممکن است در نسخه‌های فرعی Next.js کمی فرق کند. اگر سؤالی با متن کمی متفاوت دیدید، مفهوم آن را با جدول بالا تطبیق دهید. مهم‌ترین موارد این‌هاست: TypeScript روشن، App Router روشن، پوشه‌ی src خاموش و Cache Components خاموش.

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

راه میان‌بر و محدودیتش

می‌توان با گزینه‌ی --yes سؤال‌ها را رد کرد:

bash

npx create-next-app@latest devnotes --yes

این گزینه از تنظیمات ذخیره‌شده‌ی قبلی یا همان تنظیمات پیش‌فرض استفاده می‌کند. چون پیش‌فرض‌ها شامل Cache Components هستند، برای این دوره روش مناسبی نیست، مگر اینکه بعد از ساخت، پیکربندی را اصلاح کنید.

اگر پروژه را با تنظیمات پیشنهادی ساخته‌اید، فایل next.config.ts را باز کنید. اگر گزینه‌ی cacheComponents: true را دیدید، آن را حذف کنید یا مقدارش را false بگذارید. نتیجه باید چیزی شبیه این باشد:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // در این مرحله cacheComponents روشن نیست.
};

export default nextConfig;

اگر هنگام ساخت پروژه گزینه‌ی Cache Components را روی No گذاشته باشید، چیزی لازم نیست تغییر بدهید.

گام ۳: ورود به پوشه‌ی پروژه و اجرای سرور توسعه

bash

cd devnotes
npm run dev

دستور اول وارد پوشه‌ی پروژه می‌شود و دستور دوم سرور توسعه را اجرا می‌کند. جزئیات اسکریپت‌ها و Turbopack را در اجرای پروژه، اسکریپت‌ها و Turbopack بررسی می‌کنیم؛ فعلاً فقط می‌خواهیم مطمئن شویم پروژه کار می‌کند.

خروجی مورد انتظار در ترمینال

متن دقیق و شماره‌ی نسخه با سیستم شما فرق می‌کند، اما باید پیامی شبیه این ببینید:

text

▲ Next.js 16.x.x (Turbopack)
- Local:         http://localhost:3000

✓ Ready in 1.2s

گام ۴: دیدن نتیجه در مرورگر

مرورگر را باز کنید و به آدرس http://localhost:3000 بروید. صفحه‌ی شروعی که Next.js ساخته است نمایش داده می‌شود. این صفحه فقط یک نمونه‌ی اولیه است و در فصل ۲ آن را با اسکلت DevNotes جایگزین می‌کنیم.

برای متوقف‌کردن سرور، در ترمینال کلیدهای Ctrl + C را بزنید.

نگاه سریع به فایل `package.json`

فایل package.json در ریشه‌ی پروژه، نام پروژه، اسکریپت‌ها و وابستگی‌ها را نگه می‌دارد. بخشی از آن چیزی شبیه این است:

json

{
  "name": "devnotes",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  },
  "dependencies": {
    "next": "16.x.x",
    "react": "19.x.x",
    "react-dom": "19.x.x"
  }
}

scripts: دستورهایی که با npm run نام اجرا می‌شوند؛ مثلاً npm run dev.
dependencies: کتابخانه‌هایی که برنامه برای اجرا به آن‌ها نیاز دارد. می‌بینید که next، react و react-dom کنار هم هستند، چون Next.js روی React ساخته شده است.
نسخه‌ها و فهرست دقیق وابستگی‌ها (مثل TypeScript، Tailwind و ESLint) با زمان ساخت پروژه فرق می‌کند.

باز کردن پروژه در ویرایشگر

در VS Code می‌توانید از ترمینال داخل پوشه‌ی پروژه این دستور را بزنید، یا از منوی File > Open Folder پوشه‌ی devnotes را انتخاب کنید:

bash

code .

ساختار پوشه‌ها و فایل‌هایی که ابزار ساخته است در درس بعد (CH01-S05) توضیح داده می‌شود.

جمع‌بندی

برای ساخت پروژه‌ی جدید از دستور npx create-next-app@latest devnotes استفاده می‌کنیم.
تنظیمات پیشنهادیِ فعلی create-next-app، Cache Components را روشن می‌کند. برای اینکه رفتار پایه را قدم‌به‌قدم یاد بگیریم، گزینه‌ی customize را انتخاب می‌کنیم و Cache Components را در فصل ۷ و آگاهانه فعال می‌کنیم.
انتخاب‌های ما: TypeScript، ESLint، Tailwind CSS، App Router، بدون پوشه‌ی src، بدون React Compiler، بدون Cache Components، همان import alias پیش‌فرض و بدون AGENTS.md.
با npm run dev سرور توسعه اجرا می‌شود و پروژه در http://localhost:3000 در دسترس است.
در درس بعد (ساختار فایل‌ها و پوشه‌ها) ساختار فایل‌ها و پوشه‌های پروژه را بررسی می‌کنیم.

ساخت پروژه با create-next-app