TypeScript لا يرى SVG؟ حل المشكلة نهائياً

مقدمة: "Cannot find module" — ألم مألوف؟

أنت تكتب بلغة TypeScript، وتضيف إلى مشروعك أيقونة جميلة بصيغة SVG وتحاول استيرادها بالطريقة القياسية:

import Logo from './assets/logo.svg';

وفجأة يظهر لك TypeScript خطأ أحمر:

Cannot find module './assets/logo.svg' or its corresponding type declarations.

هل هذا مألوف؟ إذا واجهت هذه المشكلة ولو مرة واحدة، فأنت لست وحدك. سؤال "Unable to import svg files in typescript" على Stack Overflow حصد آلاف المشاهدات وعشرات الإجابات. المشكلة هي أن TypeScript افتراضياً لا يعرف كيفية التعامل مع الملفات غير البرمجية (SVG, PNG, CSS).

في هذه المقالة، سنشرح شرحاً كاملاً مع الكود: لماذا يحدث الخطأ وكيفية إصلاحه نهائياً. ستتعرف على declaration files، وإعداد Webpack و Vite، وكذلك كيفية كتابة أنواع SVG بشكل صحيح في مشاريع React.

لماذا لا يرى TypeScript ملفات SVG؟

TypeScript هي لغة مكتوبة بشكل صارم (strictly typed). تتحقق من الأنواع في مرحلة التجميع. عندما تكتب import Logo from './logo.svg'، يتوقع TypeScript أن الوحدة ./logo.svg تصدر شيئاً بنوع معروف. لكن SVG ليس ملف TypeScript، بل هو XML. ليس لدى TypeScript وصف مدمج لوحدات SVG.

من هنا يأتي الخطأ: لا يمكن للمترجم العثور على type declarations (إعلانات الأنواع) لهذا الملف.

هناك ثلاث طرق رئيسية لحل المشكلة:

\n
• الطريقة 1: إنشاء ملف إعلانات عام (.d.ts)
\n
• الطريقة 2: استخدام Webpack/Vite مع المحملات (loaders) الصحيحة
\n
• الطريقة 3: استيراد SVG عبر url أو raw (لحالات محددة)
\n

سنشرح كل طريقة مع أمثلة كود.

الطريقة 1: ملف declaration عام (الأكثر شيوعاً)

هذا هو الحل من Stack Overflow الذي يعمل في 90% من الحالات. تقوم بإنشاء ملف بامتداد .d.ts (مثلاً src/declarations.d.ts أو src/svg.d.ts) وتعلن عن وحدة SVG.

إليك الكود الأدنى:

// src/declarations.d.ts\ndeclare module '*.svg' {\n  const content: string;\n  export default content;\n}

ماذا يحدث هنا؟ نقول لـ TypeScript: "أي ملف بامتداد .svg هو وحدة تصدر افتراضياً نصاً (مسار الملف أو محتواه)".

إذا كنت تستخدم React وتريد استيراد SVG كمكون React (عبر @svgr/webpack أو vite-plugin-svgr)، سيكون الإعلان مختلفاً:

// src/declarations.d.ts\ndeclare module '*.svg' {\n  import React from 'react';\n  const SVGComponent: React.FC<React.SVGProps<SVGSVGElement>>;\n  export default SVGComponent;\n}

هام: تأكد من أن ملف .d.ts مضمن في ملف tsconfig.json الخاص بك. عادةً يكفي أن يكون داخل src/، ولكن إذا لم يكن كذلك، أضف المسار في حقل include:

// tsconfig.json\n{\n  "compilerOptions": {\n    // ... باقي الإعدادات\n  },\n  "include": ["src/**/*"]\n}

بعد ذلك، سيختفي الخطأ "Cannot find module" وستتمكن من استيراد SVG كالمعتاد.

الطريقة 2: إعداد Webpack أو Vite

الإعلان العام هو نصف الحل فقط. لكي يعمل الاستيراد فعلياً في وقت التشغيل (في المتصفح)، تحتاج إلى إعداد أداة التجميع (bundler).

لـ Webpack

قم بتثبيت file-loader أو url-loader:

npm install --save-dev file-loader

أضف قاعدة في webpack.config.js:

// webpack.config.