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.

أمثلة

التحقق من أنواع 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

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

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

import type { 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} />
}

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

منذ الإصدار 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"]
}

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