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 من الملف القديم jsconfig.json إلى ملف tsconfig.json الجديد، واحذف ملف jsconfig.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). يتم تضمين هذا الملف .d.ts في tsconfig.json وسيتحقق مترجم TypeScript من هذا الملف .d.ts ويقدم ملاحظات في محررك حول الروابط غير الصالحة.

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

يحتوي Next.js 13 على سلامة أنواع محسنة. وهذا يشمل:

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

جلب البيانات في 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 يجب أن يحل هذه المشكلة.

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

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

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

أسماء مسارات مختصرة و baseUrl

يدعم 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,
  },
}

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