استخدام 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 موجودة في Next.js

للعمل على مشاريع موجودة، عليك أولًا إنشاء الملف 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) وستقودك خلال عملية تثبيت الحزم المطلوبة:

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.

التوليد الساكن والتصيير من جانب الخادم في مشاريع TypeScriptمع Next.js

• يُستخدم النوع 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 فاتّبع الإرشادات الموجودة في توثيق إحضار البيانات

توجيهات الواجهة البرمجية بوجود أنواع في Next.js

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

import type { NextApiRequest, NextApiResponse } from 'next'

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

استخدام الأنواع مع التطبيقات المخصصة في Next.js

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

import type { AppProps } from 'next/app'

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

المسارت البديلة والعنوان الجذري في تهيئة TypeScript

تدعم 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

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

تجاهل أخطاء TypeScript في Next.js

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

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

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

المصادر

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