استخدام TypeScript في Next.js

تزوّدك Next.js بكل ما يلزم للعمل مع لغة TypeScript بما في ذلك تثبيتها دون الحاجة إلى تهيئة، وتقديم أنواع مدمجة لاستخدامها في صفحاتك وفي الواجهة البرمجية وغيرها الكثير.

سجل التغييرات

نسخة Next.js	التغييرات التي تتعلق بدعم TypeScript
v12.0.0	تستخدم SWC افتراضيًا في تصريف TypeScript و TSX لبناء التطبيق بشكل أسرع.
v10.2.1	تدعم Next.js استخدام ميزة التحقق التدريجي من النوع Incremental type checking عندما تمكينها في الملف tsconfig.json.

استخدام create-next-app لاعتماد لغة TypeScript مع تطبيق Next.js

بإمكانك إنشاء تطبيق بلغة TypeScript من خلال سكربت create-next-app مستخدمًا الراية ts-- أو الراية typescript-- كما يلي:

npx create-next-app@latest --ts
# أو
yarn create next-app --typescript
# أو
pnpm create next-app -- --ts

دعم لغة TypeScript مع مشاريع موجودة

لتوفير دعم لغة TypeScript على مشاريع موجودة مسبقًا، عليك أولًا إنشاء الملف tsconfig.json في المجلد الجذري للمشروع:

touch tsconfig.json

تهيئ Next.js هذا الملف بالقيم الافتراضية، وبإمكانك أيضّا تزويد هذا الملف بخيارات التصريف التي تناسبك. كما تستطيع استخدام مسار نسبي إلى الملف tsconfig.json بإسناد قيمة مناسبة للخاصية typescript.tsconfigPath ضمن ملف التهيئة next.config.js. تستخدم Next.js ابتداءً من النسخة v12.0.0 المصرِّف SWC افتراضيًا في تصريف TypeScript وملفات tsx لبناء التطبيق بشكل أسرع.

ملاحظة: تستخدم Next.js إضافة Babel للتعامل مع TypeScript إن وجد الملف babelrc.، لكن هناك بعض المحاذير وبعض خيارات التصريف التي تعالج بشكل مختلف.

نفِّذ بعد ذلك أحد الأمرين npm run dev أو yarn dev وسترشدك Next.js إلى تثبيت الحزم المطلوبة:

npm run dev

# سترى إرشادات كالتالي
#
# Please install TypeScript, @types/react, and @types/node by running:
#
#         yarn add --dev typescript @types/react @types/node
#
# ...

ستصبح بعد ذلك قادرًا على تحويل ملفات js. إلى ملفات tsx. وتستفيد من إمكانات لغة TypeScript.

ملاحظة: سيظهر ملف باسم next-env.d.ts في المجلد الجذري للمشروع، ومهمته التأكد أن أنواع Next.js قد اختارها مُصرِّف TypeScript. لا يمكن إزالة هذا الملف أو تعديله لأنه قد يتغير مع الوقت.

ملاحظة: إن النمط strict (المقيّد) للغة TypeScript معطّل تلقائيًا، لكننا ننصحك بتفعيله من خلال الملف tsconfig.json حالما تشعر بأنك تمكّنت من اللغة.

ملاحظة: يمكنك إضافة أنواع أخرى لمشروعك من خلال إضافة ملفات جديدة مثل additional.d.ts بدلًا من تعديل الملف next-env.d.ts. عليك بعد ذلك أن تشير إليها ضمن المصفوفة include في ملف التهيئة tsconfig.json.

تتحقق Next.js من الأنواع تلقائيًا عند تنفذ أمر البناء next build، لكننا ننصحك بالتحقق منها عبر محرر الشيفرة أثناء تطوير التطبيق.

إن أردت إيقاف تقارير الأخطاء، عد إلى توثيق Next.js المتعلق بتجاهل أخطاء TypeScript.

التوليد الساكن SSG والتصيير من جانب الخادم SSR

• يُستخدم النوع GetStaticProps للدالة getStaticProps.
• يُستخدم النوع GetStaticPaths للدالة getStaticPaths.
• يُستخدم النوع GetServerSideProps للدالة getServerSideProps.

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

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

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

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

ملاحظة: إن كنت تستخدم الدالة getInitialProps فاتّبع الإرشادات الموجودة في توثيق إحضار البيانات

واجهة التوجيه API Routes

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

import type { NextApiRequest, NextApiResponse } from 'next'

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

يمكنك أيضًا تحديد نوع الرد:

import type { NextApiRequest, NextApiResponse } from 'next'

type Data = {
  name: string
}

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

استخدام الأنواع مع مكون APP مخصص

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

import type { AppProps } from 'next/app'

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

المسارت البديلة والعنوان الجذري 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

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

تدعم Next.js استخدام ميزة التحقق التدريجي من النوع Incremental type checking عندما تمكينها في الملف tsconfig.json ابتداءً من النسخة 10.2.1 ويسرِّع ذلك التحقق من الأنواع في التطبيقات الضخمة، ولا بد من أن تكون نسخة TypeScript هي 4.3.2 أو أعلى لتختبر الأداء الأفضل لهذه الميزة.

تجاهل أخطاء TypeScript

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

افتح الملف next.config.js وفعّل الخيار ignoreBuildErrors في تعليمات تهيئة typescript:

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

المصادر

• الصفحة TypeScipt من توثيق Next.js الرسمي.