TypeScript

يوفر Next.js تجربة تطوير معتمدة على TypeScript كخيار أول لبناء تطبيقات React.

يأتي مع دعم مدمج لـ TypeScript لتثبيت الحزم الضرورية تلقائيًا وتهيئة الإعدادات المناسبة.

بالإضافة إلى إضافة TypeScript لمحرر الأكواد الخاص بك.

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

المشاريع الجديدة

create-next-app الآن يأتي مع TypeScript بشكل افتراضي.

npx create-next-app@latest

المشاريع الحالية

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

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

إضافة TypeScript

يتضمن 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

يوصى بشدة أن تكون على الأقل على الإصدار v4.5.2 من TypeScript للحصول على ميزات مثل معدلات النوع على أسماء الاستيراد وتحسينات الأداء.

الروابط المحددة نوعيًا

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

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

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = 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، استخدم Generic:

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>My Card</div>
    </Link>
  )
}

كيف يعمل هذا؟

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

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

يتمتع موجه التطبيق في 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 أو أداة استعلام محددة الأنواع.

خطأ TypeScript في مكون الخادم غير المتزامن

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

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

تمرير البيانات بين مكونات الخادم والعميل

عند تمرير البيانات بين مكون خادم ومكون عميل عبر الخصائص، لا تزال البيانات مسلسلة (محولة إلى سلسلة) للاستخدام في المتصفح. ومع ذلك، لا تحتاج إلى نوع خاص. يتم تحديد نوعها بنفس طريقة تمرير أي خصائص أخرى بين المكونات.

علاوة على ذلك، هناك كود أقل يحتاج إلى تسلسل، حيث أن البيانات غير المعروضة لا تعبر بين الخادم والعميل (تبقى على الخادم). هذا أصبح ممكنًا الآن فقط من خلال دعم مكونات الخادم.

أسماء مسارات واستيراد قاعدة

يدعم Next.js تلقائيًا خيارات "paths" و "baseUrl" في tsconfig.json.

يمكنك معرفة المزيد عن هذه الميزة في وثائق أسماء مسارات الوحدات.

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

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

// @ts-check

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

module.exports = nextConfig

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

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

تجاهل أخطاء TypeScript

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

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

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

افتح next.config.js وقم بتمكين خيار ignoreBuildErrors في تهيئة typescript:

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

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

عندما تحتاج إلى تعريف أنواع مخصصة، قد تميل إلى تعديل 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"]
}

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