TypeScript و Linting

پیکربندی و راه‌اندازی TypeScript

فریم‌ورک Next.js به صورت پیش‌فرض و بدون نیاز به تنظیمات پیچیده، از زبان TypeScript پشتیبانی می‌کند.

• حداقل نسخه مورد نیاز: نسخه 5.1.0 یا بالاتر

مراحل فعال‌سازی خودکار

برای اضافه کردن TypeScript به یک پروژه موجود، نیازی به نصب دستی پکیج‌ها نیست؛ کافی است مراحل زیر را دنبال کنید:

1. پسوند یکی از فایل‌های اصلی پروژه (مثلاً app/page.js) را به .ts یا .tsx تغییر دهید.

2. سرور توسعه را با دستور next dev اجرا کنید.

پس از اجرای دستور، Next.js به صورت هوشمند متوجه تغییر پسوند شده، وابستگی‌های (Dependencies) مورد نیاز را به طور خودکار نصب می‌کند و فایل تنظیمات استاندارد یعنی tsconfig.json را با پیکربندی‌های پیشنهادی به ریشه پروژه اضافه می‌نماید.

فعال‌سازی افزونه اختصاصی در محیط توسعه (IDE Plugin)

Next.js همراه با یک افزونه اختصاصی هوش‌سنجی و بررسی نوع داده (Type-checker) عرضه می‌شود. محیط‌های برنامه‌نویسی مانند VS Code می‌توانند از این قابلیت برای خطایابی پیشرفته و تکمیل خودکار کدها (Auto-completion) استفاده کنند.

برای فعال‌سازی این افزونه در نرم‌افزار VS Code مراحل زیر را انجام دهید:

1. پالت دستورات را با کلیدهای ترکیبی Ctrl + Shift + P (در مک: ⌘ + Shift + P) باز کنید.

2. عبارت TypeScript: Select TypeScript Version را جستجو کنید.

3. گزینه Use Workspace Version را انتخاب نمایید.

پیکربندی ابزارهای بررسی خطا (Set up linting)

Next.js از دو ابزار قدرتمند ESLint و Biome جهت بررسی خطاهای نگارشی و ساختاری کد پشتیبانی می‌کند. شما می‌توانید ابزار مدنظر خود را انتخاب کرده و آن را مستقیماً از طریق اسکریپت‌های فایل package.json اجرا کنید.

گزینه اول: استفاده از ESLint (مجموعه قوانین جامع و استاندارد)

اگر می‌خواهید از استاندارد رسمی و قوانین جامع ESLint استفاده کنید، اسکریپت‌های زیر را در فایل package.json قرار دهید:

{
  "scripts": {
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}

نکته مهم برای ساخت فایل تنظیمات: در صورت استفاده از ESLint، پیشنهاد می‌شود یک فایل پیکربندی صریح و مشخص به نام eslint.config.mjs ایجاد کنید. این ابزار از هر دو فرمت قدیمی (.eslintrc.*) و فرمت جدید و بهینه لایه ماژول (eslint.config.mjs) پشتیبانی می‌کند.

گزینه دوم: استفاده از Biome (بررسی‌کننده و فرمت‌کننده فوق‌سریع)

اگر سرعت اولویت اصلی شماست، ابزار Biome که فرآیند لیت کردن و فرمت‌دهی کد را با هم ادغام می‌کند، گزینه مناسبی است:

{
  "scripts": {
    "lint": "biome check",
    "format": "biome format --write"
  }
}

مهاجرت به ساختار جدید (Migration)

قانون جدید از نسخه 16 Next.js: از نسخه 16 به بعد، دستور ساخت پروژه یعنی next build دیگر فرآیند لیت کردن (Linting) را به صورت خودکار در زمان بیلد اجرا نمی‌کند. به جای آن، شما باید بررسی خطاهای کد را به صورت مستقل و از طریق اسکریپت‌های مدیریت بسته (NPM Scripts) مدیریت و اجرا کنید.

اگر پروژه قدیمی شما از دستور ساختاری داخلی next lint استفاده می‌کرد، پیشنهاد می‌شود با اجرای کد کامپایل اختصاصی (Codemod) زیر در ترمینال، اسکریپت‌های خود را به ابزار استاندارد خط فرمان ESLint (همان ESLint CLI) ارتقا دهید:

npx @next/codemod@canary next-lint-to-eslint-cli .