اجرای پروژه، اسکریپت‌ها و Turbopack

در درس «ساخت پروژه با create-next-app» پروژه را ساختیم و یک‌بار با npm run dev اجرا کردیم. در این درس دقیق‌تر می‌بینیم این دستور چه می‌کند، چهار اسکریپت اصلی پروژه برای چه کاری هستند، و Turbopack که در Next.js 16 ابزار پیش‌فرض است چه نقشی دارد.

پیش‌نیاز

  • درس «ساخت پروژه با create-next-app»
  • درس «ساختار فایل‌ها و پوشه‌ها»، به‌ویژه آشنایی با فایل package.json

اسکریپت‌های package.json

در package.json بخشی به نام scripts وجود دارد که دستورهای کوتاهی را به دستورهای اصلی نگاشت می‌کند. با npm run نام-اسکریپت اجرا می‌شوند. در پروژه‌ی ما این بخش چیزی شبیه این است:

json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}
اسکریپت دستور اصلی کاربرد
npm run dev next dev اجرای سرور توسعه برای کدنویسی روزمره
npm run build next build ساخت نسخه‌ی بهینه‌ی Production
npm run start next start اجرای نسخه‌ی ساخته‌شده؛ فقط بعد از build کار می‌کند
npm run lint eslint بررسی کیفیت کد با ESLint

اسکریپت lint مستقیماً ESLint را اجرا می‌کند. از Next.js 16 به بعد، next build دیگر به‌صورت خودکار linter را اجرا نمی‌کند، پس بررسی کد باید جداگانه و با همین اسکریپت انجام شود. جزئیات پیکربندی ESLint در درس «TypeScript، ESLint و Format کردن کد در Next.js 16» می‌آید.

دلیل وجود اسکریپت‌ها این است که شما نیازی ندارید مسیر دقیق ابزارها را بدانید؛ فقط نام اسکریپت را اجرا می‌کنید و npm ابزار درست را پیدا می‌کند. می‌توانید خودتان هم اسکریپت جدید اضافه کنید.

سرور توسعه: npm run dev

این دستور سرور توسعه را روی سیستم شما بالا می‌آورد. در این حالت پروژه برای سرعت کدنویسی بهینه است، نه برای سرعت نهایی کاربر. ویژگی‌های مهمش:

  • بارگذاری مجدد سریع (Fast Refresh): با ذخیره‌ی فایل، تغییر بدون ریفرش کامل صفحه در مرورگر دیده می‌شود و اغلب State کامپوننت‌ها هم حفظ می‌شود.
  • کامپایل در لحظه: مسیرها معمولاً هنگام اولین بازدید کامپایل می‌شوند، پس اولین باز کردن یک صفحه کمی کندتر از دفعات بعد است.
  • پیام‌های خطای کامل: خطاها با جزئیات روی صفحه نمایش داده می‌شوند.

رفتار برنامه در حالت توسعه همیشه دقیقاً مثل Production نیست؛ به‌ویژه در موضوع کش. هر جا این تفاوت برای فهم موضوع مهم باشد، آن را در همان درس توضیح می‌دهیم.

تغییر پورت

پورت پیش‌فرض 3000 است. اگر این پورت اشغال باشد یا بخواهید پورت دیگری بدهید، گزینه‌ی -p را به دستور اصلی بدهید. برای عبور آرگومان به اسکریپت npm از -- استفاده می‌کنیم:

bash
npm run dev -- -p 4000

حالا پروژه روی http://localhost:4000 اجرا می‌شود.

Turbopack چیست؟

برای اجرای پروژه، کد شما (TypeScript، JSX، CSS و ...) باید پردازش و به فایل‌هایی تبدیل شود که مرورگر و سرور بفهمند. ابزاری که این کار را انجام می‌دهد Bundler نام دارد. Turbopack همان Bundler ساخته‌شده‌ی خود تیم Next.js است.

در Next.js 16، Turbopack پایدار و پیش‌فرض است؛ هم برای next dev و هم برای next build. بنابراین چیزی برای فعال‌کردن آن لازم نیست و دستورهایی که تا اینجا اجرا کرده‌ایم از آن استفاده می‌کنند. هدف اصلی آن سریع‌ترشدن شروع سرور، به‌روزرسانی در حین توسعه و Build است.

اگر لازم شد به Webpack برگردیم

Webpack، Bundler قبلی و پیش‌فرض Next.js، هنوز قابل استفاده است. اگر پروژه‌ای به تنظیمات سفارشی Webpack وابسته باشد، می‌توان با گزینه‌ی --webpack آن را انتخاب کرد:

bash
npx next dev --webpack
npx next build --webpack

در پروژه‌ی DevNotes نیازی به این گزینه نداریم و همه‌ی مثال‌های دوره با Turbopack سازگارند. پیکربندی خود Turbopack، در صورت نیاز، با گزینه‌ی turbopack در next.config.ts انجام می‌شود (در Next.js 16 این گزینه در سطح بالای پیکربندی قرار دارد، نه زیر experimental). ما در این دوره به آن دست نمی‌زنیم.

ساخت نسخه‌ی Production: npm run build

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

bash
npm run build

این دستور کد را کامپایل و بهینه می‌کند، خطاهای TypeScript را بررسی می‌کند و خروجی را در پوشه‌ی .next می‌گذارد. در پایان، گزارشی از مسیرهای برنامه چاپ می‌کند. فرم گزارش چیزی شبیه این است:

text
Route (app)
┌ ○ /
└ ○ /_not-found

○  (Static)  prerendered as static content

شکل دقیق خروجی و نمادهای آن به نسخه‌ی فرعی و پیکربندی پروژه بستگی دارد. نکته‌ی مهم این است که این جدول نشان می‌دهد هر مسیر به چه شکلی رندر می‌شود. معنی نمادها را در فصل «Rendering و Data Fetching» می‌فهمیم.

اجرای نسخه‌ی ساخته‌شده: npm run start

bash
npm run build
npm run start

next start نسخه‌ی ساخته‌شده را اجرا می‌کند و به همان فایل‌های .next نیاز دارد. اگر قبل از build آن را بزنید، Next.js خطا می‌دهد و می‌گوید نسخه‌ی Production پیدا نشد. این حالت شبیه چیزی است که روی سرور واقعی اجرا می‌شود. جزئیاتش را در درس‌های «Build و بررسی خطاها» و «اجرای Production به‌صورت محلی» در فصل «Build، Runtime و استقرار» می‌بینیم.

مقایسه‌ی حالت توسعه و Production

ویژگی npm run dev npm run build و npm run start
هدف راحتی و سرعت توسعه سرعت و بهینگی برای کاربر نهایی
مراحل یک دستور، بدون Build جداگانه اول ساخت، بعد اجرا
تغییر کد با ذخیره‌ی فایل فوری دیده می‌شود باید دوباره build بگیرید
خطاها جزئیات کامل روی صفحه پیام‌های محدودتر برای کاربر
کاربرد کدنویسی روزمره بررسی رفتار واقعی و انتشار

تمرین کوتاه

  1. سرور توسعه را اجرا کنید و فایل app/page.tsx را باز کنید.
  2. یکی از متن‌های داخل صفحه را عوض کنید و ذخیره کنید.
  3. بدون ریفرش دستی، تغییر را در مرورگر ببینید.
  4. سرور را با Ctrl + C متوقف کنید، سپس npm run build و بعد npm run start را اجرا کنید.
  5. در http://localhost:3000 نسخه‌ی Production را ببینید. حالا اگر دوباره متن را عوض کنید، تا build مجدد تغییری دیده نمی‌شود.

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

در حالت dev تغییر متن فوراً در مرورگر ظاهر می‌شود. در حالت start همان تغییر فقط بعد از اجرای دوباره‌ی npm run build دیده می‌شود. این تفاوت نشان می‌دهد این دو حالت دو شیوه‌ی اجرای کاملاً متفاوت هستند.

جمع‌بندی

  • چهار اسکریپت اصلی پروژه dev، build، start و lint هستند و هرکدام با npm run اجرا می‌شوند.
  • npm run dev سرور توسعه با Fast Refresh است و برای کدنویسی روزمره استفاده می‌شود؛ پورت پیش‌فرض آن ۳۰۰۰ است.
  • npm run build نسخه‌ی بهینه می‌سازد و npm run start آن را اجرا می‌کند؛ ترتیب این دو مهم است.
  • Turbopack در Next.js 16 به‌صورت پیش‌فرض برای dev و build استفاده می‌شود و در صورت نیاز می‌توان با گزینه‌ی --webpack به Webpack برگشت.
  • از Next.js 16، next build خودکار linter را اجرا نمی‌کند و باید npm run lint را جداگانه بزنید.
  • در درس بعد، «مهم‌ترین تغییرات Next.js 16»، تغییرات اصلی این نسخه را یکجا مرور می‌کنیم.