استخدام 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
) وستقودك 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.
التوليد الساكن والتصيير من جانب الخادم في مشاريع 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 الرسمي.