TypeScript

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

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

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

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

npx create-next-app@latest

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

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

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

الحد الأدنى لإصدار TypeScript

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

التوليد الثابت وعرض جانب الخادم

لـ getStaticProps و getStaticPaths و getServerSideProps، يمكنك استخدام الأنواع GetStaticProps و GetStaticPaths و GetServerSideProps على التوالي:

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'

export const getStaticProps = (async (context) => {
  // ...
}) satisfies GetStaticProps

export const getStaticPaths = (async () => {
  // ...
}) satisfies GetStaticPaths

export const getServerSideProps = (async (context) => {
  // ...
}) satisfies GetServerSideProps

معلومة مفيدة: تمت إضافة satisfies إلى TypeScript في الإصدار 4.9. نوصي بالترقية إلى أحدث إصدار من TypeScript.

مسارات API

إليك مثال لكيفية استخدام الأنواع المدمجة لمسارات API:

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: 'John Doe' })
}

يمكنك أيضًا تحديد نوع بيانات الاستجابة:

import type { NextApiRequest, NextApiResponse } from 'next'

type Data = {
  name: string
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  res.status(200).json({ name: 'John Doe' })
}

App مخصص

إذا كان لديك تطبيق App مخصص، يمكنك استخدام النوع المدمج AppProps وتغيير اسم الملف إلى ./pages/_app.tsx كما يلي:

import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

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

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

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