TypeScript no ve SVG? Resolvemos el problema de una vez por todas

Introducción: "Cannot find module" — ¿un dolor familiar?

Estás escribiendo en TypeScript, agregas un bonito icono en formato SVG a tu proyecto e intentas importarlo de la forma estándar:

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

Y entonces TypeScript te muestra un error en rojo:

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

¿Te suena familiar? Si alguna vez te has enfrentado a este problema, no estás solo. La pregunta "Unable to import svg files in typescript" en Stack Overflow ha acumulado miles de visitas y decenas de respuestas. El problema es que TypeScript, por defecto, no sabe cómo manejar archivos que no son de código (SVG, PNG, CSS).

En este artículo, analizaremos una explicación completa con código: por qué ocurre el error y cómo solucionarlo de una vez por todas. Aprenderás sobre declaration files, configuración de Webpack y Vite, así como la forma correcta de tipar SVG en proyectos React.

¿Por qué TypeScript no ve SVG?

TypeScript es un lenguaje fuertemente tipado. Verifica los tipos en tiempo de compilación. Cuando escribes import Logo from './logo.svg', TypeScript espera que el módulo ./logo.svg exporte algo con un tipo conocido. Pero SVG no es un archivo TypeScript, es XML. TypeScript no tiene una descripción incorporada para módulos SVG.

De ahí el error: el compilador no puede encontrar type declarations (declaraciones de tipos) para este archivo.

Existen tres formas principales de resolver el problema:

\n
• Forma 1: Crear un archivo de declaración global (.d.ts)
\n
• Forma 2: Usar Webpack/Vite con los cargadores correctos
\n
• Forma 3: Importar SVG mediante url o raw (para casos específicos)
\n

Analizaremos cada forma con ejemplos de código.

Forma 1: Archivo de declaración global (el más popular)

Esta es la solución de Stack Overflow que funciona en el 90% de los casos. Creas un archivo con extensión .d.ts (por ejemplo, src/declarations.d.ts o src/svg.d.ts) y declaras el módulo para SVG.

Aquí está el código mínimo:

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

¿Qué sucede aquí? Le decimos a TypeScript: "Cualquier archivo con extensión .svg es un módulo que exporta por defecto una cadena (ruta del archivo o contenido)".

Si usas React y quieres importar SVG como un componente React (a través de @svgr/webpack o vite-plugin-svgr), la declaración será diferente:

// 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}

Importante: Asegúrate de que el archivo .d.ts esté incluido en tu tsconfig.json. Normalmente es suficiente con que esté dentro de src/, pero si no es así, agrega la ruta en el campo include:

// tsconfig.json\n{\n  "compilerOptions": {\n    // ... otras configuraciones\n  },\n  "include": ["src/**/*"]\n}

Después de esto, el error "Cannot find module" desaparecerá y podrás importar SVG como de costumbre.

Forma 2: Configuración de Webpack o Vite

La declaración global es solo la mitad del trabajo. Para que la importación realmente funcione en tiempo de ejecución (en el navegador), debes configurar el empaquetador.

Para Webpack

Instala file-loader o url-loader:

npm install --save-dev file-loader

Agrega la regla en webpack.config.js:

// webpack.config.