خطأ JSX في TypeScript: علامة --jsx وكيفية إصلاحه

«Cannot use JSX unless the '--jsx' flag is provided» — ما هذا الوحش؟

تخيل: أنت تكتب بحماس أول تطبيق React لك باستخدام TypeScript. الكود يبدو مثالياً، المكونات مدروسة، والمزاج قتالي. تقوم بتشغيل التجميع — وفجأة ترى هذه الرسالة الباردة المخيفة:

Cannot use JSX unless the '--jsx' flag is provided.

مألوفة؟ لا تقلق، لست وحدك. هذا الخطأ هو أحد أكثر الأسئلة شيوعاً على Stack Overflow بآلاف المشاهدات. ولكن، مثل أي لغز، له حل بسيط وأنيق. في هذه المقالة، لن نصلح الخطأ فحسب، بل سنفهم لماذا يحدث وكيفية إعداد TypeScript للعمل مع JSX مرة واحدة وإلى الأبد.

بالمناسبة، إذا كنت قد بدأت للتو رحلتك في عالم TypeScript وReact، أوصي أيضاً بالاطلاع على موادنا حول أساسيات TypeScript — سيساعدك ذلك على تجنب العديد من المزالق في البداية.

لماذا يعترض TypeScript على JSX؟

دعنا نفهم طبيعة هذا الخطأ. TypeScript هي لغة صارمة لا تفهم بناء الجملة الشبيه بـ HTML الخاص بـ JSX بشكل افتراضي. عندما تكتب:

const element = <h1>Hello, World!</h1>;

يرى TypeScript ليس كوداً مألوفاً، بل شيئاً غريباً. لشرح للمترجم أن هذه الأقواس الزاوية ليست خطأ، بل جزء من مكون React الخاص بك، يجب عليك تحديد العلامة --jsx بشكل صريح. هذا مثل إعطاء مترجم لـ TypeScript: «اسمع، هذه الإنشاءات هي JSX صالح، لا تلمسها، بل تعامل معها بشكل صحيح».

يظهر الخطأ في ثلاث حالات نموذجية:

\n
• مشروع جديد — نسيت إعداد tsconfig.json للعمل مع React؛
\n
• الترحيل من JavaScript — تقوم بتحويل مشروع إلى TypeScript، لكنك لم تقم بتحديث التكوين؛
\n
• استخدام ملفات .tsx — قمت بإنشاء ملف بامتداد .tsx، لكن المترجم لا يعرف ماذا يفعل به.
\n

الخبر السار: الإصلاح يستغرق أقل من دقيقة. الخبر السيئ: إذا كنت لا تعرف أين تبحث، فقد تضيع ساعات. دعنا نصلح هذا مرة واحدة وإلى الأبد.

الحل خطوة بخطوة: إعداد tsconfig.json

الطريقة الأصح والأكثر توصية هي إضافة إعداد JSX إلى ملف tsconfig.json الخاص بك. هذا الملف هو عقل مشروع TypeScript الخاص بك. هنا سنخبر المترجم بكيفية معالجة JSX.

الخطوة 1: افتح tsconfig.json

ابحث عن ملف tsconfig.json في جذر مشروعك. إذا لم يكن موجوداً، قم بإنشائه. يمكن القيام بذلك باستخدام الأمر:

npx tsc --init

سينشئ هذا الأمر ملف تكوين أساسي مع العديد من الخيارات المعلقة. لا تقلق — سنقوم بتغيير سطر واحد فقط.

الخطوة 2: أضف خيار jsx

داخل كائن compilerOptions، أضف (أو قم بإلغاء تعليق) السطر:

{\n  "compilerOptions": {\n    "jsx": "react-jsx",\n    // باقي الإعدادات...\n  }\n}

لاحظ: القيمة "react-jsx" هي المعيار الحديث لـ React 17+ وReact 18. إذا كنت تستخدم إصداراً قديماً من React (قبل 17)، يمكنك استخدام "react". لكني أوصي بشدة باستخدام "react-jsx" — فهو ينتج كوداً أكثر تحسيناً ولا يتطلب استيراد React في كل ملف.

الخطوة 3: احفظ وأعد تشغيل التجميع

بعد حفظ التغييرات، يجب أن يختفي الخطأ. قم بتشغيل البناء مرة أخرى:

npm run build\n# أو\nnpx tsc

إذا قمت بكل شيء بشكل صحيح، سيتوقف المترجم عن الاعتراض، وسيتم تشغيل تطبيقك.

طرق بديلة: للمستخدمين المتقدمين

أحياناً تحتاج إلى التحقق بسرعة من فرضية أو تشغيل سكريبت أحادي الملف. في مثل هذه الحالات، يمكنك استخدام علامة سطر الأوامر:

npx tsc --jsx react-jsx app.tsx

هذا حل مؤقت — لا يغير الإعدادات العامة للمشروع.