Vite: Solucionar "Failed to resolve import" (alias de rutas)

Acabas de configurar alias de rutas en tu proyecto Vite, reemplazando esas engorrosas importaciones ../../../components con rutas limpias como @/components. Pero ahora Vite lanza un error frustrante: “Failed to resolve import”. Esto ocurre porque Vite y TypeScript manejan la resolución de módulos de manera diferente, y solucionarlo requiere sincronizar dos configuraciones separadas.

Esta guía te muestra exactamente cómo corregir los errores de alias de rutas en Vite usando dos métodos probados: configuración manual para control total, o el plugin automatizado vite-tsconfig-paths para mayor simplicidad.

El Error “Failed to resolve import” en Vite

El error Vite Failed to resolve import aparece cuando tu bundler no puede localizar módulos usando tus alias de rutas personalizados. Verás variaciones como:

• [vite] Internal server error: Failed to resolve import "@/components/Header"
• Cannot find module '@/utils' or its corresponding type declarations
• Error de TypeScript TS2307 en tu IDE

Estos errores bloquean tu servidor de desarrollo, rompen el hot module replacement y previenen builds exitosos—convirtiendo lo que debería ser un impulso de productividad en un obstáculo.

Entendiendo Por Qué Fallan los Alias de Rutas en Vite

El Problema de las Dos Configuraciones

Vite usa Rollup para el bundling, mientras que TypeScript maneja la verificación de tipos por separado. Cada herramienta necesita su propia configuración:

• Vite necesita resolve.alias en vite.config.ts para el bundling de módulos
• TypeScript necesita paths en tsconfig.json para la verificación de tipos y soporte del IDE

Cuando estas configuraciones no coinciden, obtienes errores de resolución de importaciones. Vite podría entender @/components, pero TypeScript no—o viceversa.

Causas Comunes de Errores de Importación

Tres problemas causan la mayoría de errores de resolve alias en Vite:

1. Tipos de Node.js faltantes: Usar path.resolve() sin @types/node
2. Discrepancias de sintaxis: Vite usa notación de objeto mientras TypeScript usa patrones de array
3. Conflictos de formato de módulo: Usar variables específicas de CommonJS como __dirname en proyectos ESM

Método 1: Configuración Manual para Alias de TypeScript en Vite

Paso 1: Configurar vite.config.ts

Primero, instala los tipos requeridos de Node.js:

npm install -D @types/node

Luego actualiza tu configuración de Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
      '@components': fileURLToPath(new URL('./src/components', import.meta.url)),
      '@utils': fileURLToPath(new URL('./src/utils', import.meta.url))
    }
  }
})

Para proyectos CommonJS, puedes usar path.resolve() con __dirname:

// vite.config.ts (CommonJS)
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils')
    }
  }
})

Paso 2: Actualizar tsconfig.json

Configura TypeScript para reconocer los mismos alias:

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

Nota la diferencia de sintaxis: Vite usa '@components' mientras TypeScript usa "@components/*" con valores de array.

Verificando tu Configuración

Prueba tu configuración con una importación:

// Antes: import Button from '../../../components/Button'
import Button from '@components/Button'

Tu IDE debería proporcionar sugerencias de autocompletado, y npm run dev debería iniciar sin errores.

Método 2: Configuración Automatizada con vite-tsconfig-paths

Instalación y Configuración Básica

El plugin vite-tsconfig-paths sincroniza automáticamente tus rutas de TypeScript con Vite:

npm install -D vite-tsconfig-paths

Actualiza tu configuración de Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [react(), tsconfigPaths()]
})

Eso es todo. El plugin lee las rutas de tu tsconfig.json y configura Vite automáticamente.

Beneficios Sobre la Configuración Manual

• Única fuente de verdad: Actualiza solo tsconfig.json
• Sin errores de sincronización: Los alias siempre coinciden
• Archivos de configuración más limpios: Menos código repetitivo
• Soporte para monorepos: Maneja configuraciones complejas de workspace

Solución de Problemas de Errores de Resolve Alias en Vite

Proyectos JavaScript Sin TypeScript

Para proyectos JavaScript, crea un jsconfig.json en su lugar:

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

El plugin vite-tsconfig-paths también funciona con jsconfig.json.

Monorepos y Escenarios Avanzados

En monorepos, asegúrate de que tus rutas sean relativas a la raíz del workspace:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["packages/app/src/*"],
      "@shared/*": ["packages/shared/src/*"]
    }
  }
}

Para usuarios de Windows, usa siempre barras diagonales (/) en las configuraciones de rutas—tanto Vite como TypeScript las normalizan correctamente.

Discrepancias entre Build y Desarrollo

Si los alias funcionan en desarrollo pero fallan durante el build:

1. Verifica problemas de sensibilidad a mayúsculas/minúsculas (especialmente en Linux/macOS)
2. Asegúrate de que baseUrl esté configurado correctamente
3. Verifica que todas las rutas con alias existan en tu salida de build
4. Comprueba que tu herramienta de build preserve la configuración de alias

Referencia Rápida: Manual vs vite-tsconfig-paths

Conclusión

Solucionar los errores Vite Failed to resolve import se reduce a alinear la resolución de módulos entre Vite y TypeScript. El método manual te da control preciso sobre ambas configuraciones, mientras que vite-tsconfig-paths elimina por completo los dolores de cabeza de sincronización.

Para la mayoría de proyectos, comienza con vite-tsconfig-paths—es más simple y previene la divergencia de configuración. Cambia a configuración manual solo cuando necesites estrategias de aliasing diferentes entre desarrollo y producción, o cuando trabajes con configuraciones de build inusuales que requieran lógica de resolución personalizada.

Preguntas Frecuentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.