TypeScript

يأتي Next.js مع دعم مدمج لـ TypeScript، حيث يقوم تلقائيًا بتثبيت الحزم الضرورية وضبط الإعدادات المناسبة عند إنشاء مشروع جديد باستخدام create-next-app.

لإضافة TypeScript إلى مشروع موجود، قم بإعادة تسمية ملف إلى .ts / .tsx. ثم قم بتشغيل next dev و next build لتثبيت التبعيات الضرورية تلقائيًا وإضافة ملف tsconfig.json مع خيارات التهيئة الموصى بها.

معلومة مفيدة: إذا كان لديك بالفعل ملف jsconfig.json، انسخ خيار paths من الملف القديم jsconfig.json إلى ملف tsconfig.json الجديد، ثم احذف الملف القديم jsconfig.json.

إضافة IDE

يتضمن Next.js مكونًا إضافيًا مخصصًا لـ TypeScript ومدقق أنواع، والذي يمكن لـ VSCode ومحررات الأكواد الأخرى استخدامه للتحقق المتقدم من الأنواع والإكمال التلقائي.

يمكنك تمكين المكون الإضافي في VS Code عن طريق:

1. فتح لوحة الأوامر (Ctrl/⌘ + Shift + P)
2. البحث عن "TypeScript: Select TypeScript Version"
3. اختيار "Use Workspace Version"

الآن، عند تحرير الملفات، سيتم تفعيل المكون الإضافي المخصص. عند تشغيل next build، سيتم استخدام مدقق الأنواع المخصص.

يمكن للمكون الإضافي لـ TypeScript المساعدة في:

• التحذير إذا تم تمرير قيم غير صالحة لـ خيارات تكوين القطعة.
• عرض الخيارات المتاحة والوثائق في السياق.
• التأكد من استخدام توجيه 'use client' بشكل صحيح.
• التأكد من أن خطافات العميل (مثل useState) تُستخدم فقط في مكونات العميل.

🎥 شاهد: تعرف على المكون الإضافي المدمج لـ TypeScript → YouTube (3 دقائق)

أمان الأنواع من البداية إلى النهاية

يتمتع موجه تطبيق Next.js بأمان أنواع محسن. وهذا يشمل:

1. عدم تسلسل البيانات بين وظيفة الجلب والصفحة: يمكنك استخدام fetch مباشرة في المكونات والتخطيطات والصفحات على الخادم. هذه البيانات لا تحتاج إلى تسلسل (تحويل إلى سلسلة) لتمريرها إلى جانب العميل للاستهلاك في React. بدلاً من ذلك، نظرًا لأن app يستخدم مكونات الخادم افتراضيًا، يمكننا استخدام قيم مثل Date و Map و Set والمزيد دون أي خطوات إضافية. سابقًا، كنت بحاجة إلى كتابة الحدود بين الخادم والعميل يدويًا باستخدام أنواع خاصة بـ Next.js.
2. تدفق بيانات مبسط بين المكونات: مع إزالة _app لصالح التخطيطات الجذرية، أصبح من الأسهل الآن تصور تدفق البيانات بين المكونات والصفحات. سابقًا، كان تدفق البيانات بين pages الفردية و _app صعب الكتابة وقد يؤدي إلى أخطاء مربكة. مع جلب البيانات المترافق في موجه التطبيق، لم يعد هذا مشكلة.

جلب البيانات في Next.js يوفر الآن أمان أنواع قريبًا من البداية إلى النهاية قدر الإمكان دون أن يكون تقييديًا بشأن اختيار قاعدة البيانات أو مزود المحتوى.

يمكننا كتابة بيانات الاستجابة كما تتوقع مع TypeScript العادي. على سبيل المثال:

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // قيمة الإرجاع *ليست* مسلسلة
  // يمكنك إرجاع Date، Map، Set، إلخ.
  return res.json()
}

export default async function Page() {
  const name = await getData()

  return '...'
}

لأمان أنواع كامل من البداية إلى النهاية، يتطلب هذا أيضًا أن تدعم قاعدة البيانات أو مزود المحتوى الخاص بك TypeScript. يمكن أن يكون ذلك من خلال استخدام ORM أو أداة بناء استعلامات آمنة للأنواع.

أمثلة

التحقق من أنواع next.config.ts

يمكنك استخدام TypeScript واستيراد الأنواع في تكوين Next.js الخاص بك باستخدام next.config.ts.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* خيارات التهيئة هنا */
}

export default nextConfig

معلومة مفيدة: دقة الوحدات في next.config.ts محدودة حاليًا بـ CommonJS. قد يتسبب هذا في عدم توافق مع الحزم التي تعمل فقط بـ ESM عند تحميلها في next.config.ts.

عند استخدام ملف next.config.js، يمكنك إضافة بعض التحقق من الأنواع في بيئة التطوير الخاصة بك باستخدام JSDoc كما يلي:

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* خيارات التهيئة هنا */
}

module.exports = nextConfig

روابط مكتوبة بشكل ثابت

يمكن لـ Next.js كتابة الروابط بشكل ثابت لمنع الأخطاء المطبعية وغيرها عند استخدام next/link، مما يحسن أمان الأنواع عند التنقل بين الصفحات.

لتفعيل هذه الميزة، يجب تمكين experimental.typedRoutes ويجب أن يستخدم المشروع TypeScript.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

export default nextConfig

سيقوم Next.js بإنشاء تعريف للروابط في .next/types يحتوي على معلومات حول جميع المسارات الموجودة في تطبيقك، والتي يمكن لـ TypeScript استخدامها لتقديم ملاحظات في محررك حول الروابط غير الصالحة.

حاليًا، يتضمن الدعم التجريبي أي سلسلة حرفية، بما في ذلك الأجزاء الديناميكية. بالنسبة للسلاسل غير الحرفية، تحتاج حاليًا إلى تحويل href يدويًا باستخدام as Route:

import type { Route } from 'next';
import Link from 'next/link'

// لا تظهر أخطاء TypeScript إذا كان href مسارًا صالحًا
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// تظهر أخطاء TypeScript إذا كان href ليس مسارًا صالحًا
<Link href="/aboot" />

لقبول href في مكون مخصص يغلف next/link، استخدم عامًا:

import type { Route } from 'next'
import Link from 'next/link'

function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>بطاقتي</div>
    </Link>
  )
}

كيف يعمل هذا؟

عند تشغيل next dev أو next build، ينشئ Next.js ملف .d.ts مخفيًا داخل .next يحتوي على معلومات حول جميع المسارات الموجودة في تطبيقك (جميع المسارات الصالحة كنوع href لـ Link). يتم تضمين هذا الملف .d.ts في tsconfig.json وسيتحقق مترجم TypeScript من هذا الملف .d.ts ويقدم ملاحظات في محررك حول الروابط غير الصالحة.

مع مكونات الخادم غير المتزامنة

لاستخدام مكون خادم async مع TypeScript، تأكد من استخدام TypeScript 5.1.3 أو أعلى و @types/react 18.2.8 أو أعلى.

إذا كنت تستخدم إصدارًا أقدم من TypeScript، فقد ترى خطأ نوع 'Promise<Element>' is not a valid JSX element. التحديث إلى أحدث إصدار من TypeScript و @types/react يجب أن يحل هذه المشكلة.

التحقق التدريجي من الأنواع

منذ الإصدار v10.2.1 يدعم Next.js التحقق التدريجي من الأنواع عند تمكينه في ملف tsconfig.json الخاص بك، وهذا يمكن أن يساعد في تسريع التحقق من الأنواع في التطبيقات الكبيرة.

تعطيل أخطاء TypeScript في الإنتاج

يفشل Next.js في بناء الإنتاج (next build) عند وجود أخطاء TypeScript في مشروعك.

إذا كنت ترغب في أن يقوم Next.js بإنتاج كود الإنتاج بشكل خطير حتى عند وجود أخطاء في تطبيقك، يمكنك تعطيل خطوة التحقق من الأنواع المدمجة.

إذا تم التعطيل، تأكد من أنك تقوم بإجراء عمليات التحقق من الأنواع كجزء من عملية البناء أو النشر، وإلا فقد يكون هذا خطيرًا جدًا.

افتح next.config.ts وقم بتمكين خيار ignoreBuildErrors في تكوين typescript:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  typescript: {
    // !! تحذير !!
    // السماح بشكل خطير بإكمال بناء الإنتاج بنجاح حتى إذا
    // كان مشروعك يحتوي على أخطاء أنواع.
    // !! تحذير !!
    ignoreBuildErrors: true,
  },
}

export default nextConfig

معلومة مفيدة: يمكنك تشغيل tsc --noEmit للتحقق من أخطاء TypeScript بنفسك قبل البناء. هذا مفيد لخطوط أنابيب CI/CD حيث ترغب في التحقق من أخطاء TypeScript قبل النشر.

تعريفات الأنواع المخصصة

عندما تحتاج إلى تعريف أنواع مخصصة، قد تميل إلى تعديل next-env.d.ts. ومع ذلك، يتم إنشاء هذا الملف تلقائيًا، لذا فإن أي تغييرات تقوم بها ستتم الكتابة فوقها. بدلاً من ذلك، يجب عليك إنشاء ملف جديد، لنسميه new-types.d.ts، والإشارة إليه في tsconfig.json الخاص بك:

{
  "compilerOptions": {
    "skipLibCheck": true
    //...مختصر...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

تغييرات الإصدارات