Solución: Cannot find module or its corresponding type declarations en TypeScript

¿Por qué ocurre?

TypeScript no puede localizar el módulo que intentas importar. Las razones más frecuentes son: el paquete npm no está instalado, el paquete existe pero no incluye tipos y necesita un paquete @types separado, la ruta de importación es incorrecta, o la configuración de paths en tsconfig.json no coincide con la estructura real del proyecto.

Solución paso a paso

Caso 1 — El paquete no está instalado:

# Instala el paquete npm install nombre-del-paquete

# Si es una dependencia de desarrollo npm install -D nombre-del-paquete

Caso 2 — El paquete no incluye tipos (el más común):

Muchos paquetes de npm están escritos en JavaScript puro sin tipos. TypeScript necesita un archivo de declaraciones separado:

# Busca e instala el paquete de tipos correspondiente npm install -D @types/express npm install -D @types/lodash npm install -D @types/node

# Para saber si existe un @types para tu paquete: # https://www.typescriptlang.org/dt/search

Si no existe @types/nombre-paquete, crea una declaración manual:

// src/types/nombre-paquete.d.ts
declare module 'nombre-paquete';
// Esto silencia el error, aunque perderás el autocompletado

Caso 3 — Ruta relativa incorrecta:

// ❌ Ruta mal escrita
import { helper } from '../utlis/helper';   // typo en "utils"
import { config } from './config.ts';        // no uses .ts en imports// ✅ Correcto
import { helper } from '../utils/helper';
import { config } from './config';           // sin extensión

Caso 4 — Alias de paths no configurado:

// tsconfig.json — añade paths
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

// ✅ Ahora funciona
import { helper } from '@/utils/helper';

Caso 5 — node_modules/@types corrompido:

rm -rf node_modules
npm install

Cómo evitarlo en el futuro

Configura `strict: true` en tsconfig.json para detectar estos errores antes de ejecutar el código. Instala siempre los @types correspondientes al añadir una nueva dependencia. Usa los alias de paths desde el inicio del proyecto para evitar rutas relativas largas y frágiles.