Solución: Error 'Failed to resolve import' en Vite (Alias y Rutas)

¿Por qué ocurre?

Vite no puede resolver una ruta de import. Las causas más comunes: usas alias como @/ sin configurarlos en vite.config, copias código de IA que asume alias que no tienes, falta la extensión del archivo, o tsconfig.json tiene paths pero Vite no los conoce.

Solución paso a paso

Paso 1 — Configura los alias en vite.config.ts:

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils'),
    },
  },
});

Paso 2 — Sincroniza con tsconfig.json (si usas TypeScript):

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

> ⚠️ Ambos archivos deben coincidir. Si solo configuras tsconfig, TypeScript lo entiende pero Vite no puede resolver la ruta al hacer build.

Paso 3 — Si el error es por extensiones de archivo:

// ❌ Vite no resuelve automáticamente todas las extensiones
import { helper } from './utils/helper';// ✅ Especifica la extensión o configura resolve.extensions
import { helper } from './utils/helper.ts';

O configura las extensiones en Vite:

// vite.config.ts
export default defineConfig({
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
  },
});

Paso 4 — Si es un paquete npm no instalado:

# Verifica si el paquete existe npm ls nombre-del-paquete

# Si no aparece, instálalo npm install nombre-del-paquete

Paso 5 — Limpia la caché de Vite:

# Borra la caché y reinicia
rm -rf node_modules/.vite
npm run dev

Cómo evitarlo en el futuro

Configura los alias en vite.config.ts Y en tsconfig.json desde el inicio del proyecto. Cuando pegues código de IA que usa alias como @/, verifica que los tengas configurados. Usa el plugin vite-tsconfig-paths si quieres que Vite lea los paths de tsconfig automáticamente: npm install -D vite-tsconfig-paths.