Vite : Résoudre l'erreur « Failed to resolve import » (alias de chemins)

Vous venez de configurer des alias de chemins dans votre projet Vite, remplaçant ces importations encombrantes ../../../components par des chemins propres @/components. Mais maintenant Vite génère une erreur frustrante : « Failed to resolve import ». Cela se produit parce que Vite et TypeScript gèrent la résolution des modules différemment, et la correction nécessite de synchroniser deux configurations distinctes.

Ce guide vous montre exactement comment corriger les erreurs d’alias de chemins Vite en utilisant deux méthodes éprouvées : la configuration manuelle pour un contrôle total, ou le plugin automatisé vite-tsconfig-paths pour plus de simplicité.

L’erreur « Failed to resolve import » dans Vite

L’erreur Vite Failed to resolve import apparaît lorsque votre bundler ne peut pas localiser les modules en utilisant vos alias de chemins personnalisés. Vous verrez des variantes comme :

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

Ces erreurs bloquent votre serveur de développement, cassent le remplacement de module à chaud (hot module replacement) et empêchent les builds réussis—transformant ce qui devrait être un gain de productivité en obstacle.

Comprendre pourquoi les alias de chemins Vite échouent

Le problème des deux configurations

Vite utilise Rollup pour le bundling, tandis que TypeScript gère la vérification de types séparément. Chaque outil nécessite sa propre configuration :

• Vite a besoin de resolve.alias dans vite.config.ts pour le bundling des modules
• TypeScript a besoin de paths dans tsconfig.json pour la vérification de types et le support IDE

Lorsque ces configurations ne correspondent pas, vous obtenez des erreurs de résolution d’importation. Vite peut comprendre @/components, mais pas TypeScript—ou vice versa.

Déclencheurs courants des erreurs d’importation

Trois problèmes causent la plupart des erreurs Vite resolve alias :

1. Types Node.js manquants : Utilisation de path.resolve() sans @types/node
2. Incompatibilités de syntaxe : Vite utilise la notation objet tandis que TypeScript utilise des patterns de tableaux
3. Conflits de format de module : Utilisation de variables spécifiques à CommonJS comme __dirname dans des projets ESM

Méthode 1 : Configuration manuelle pour les alias TypeScript Vite

Étape 1 : Configurer vite.config.ts

D’abord, installez les types Node.js requis :

npm install -D @types/node

Ensuite, mettez à jour votre configuration 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))
    }
  }
})

Pour les projets CommonJS, vous pouvez utiliser path.resolve() avec __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')
    }
  }
})

Étape 2 : Mettre à jour tsconfig.json

Configurez TypeScript pour reconnaître les mêmes alias :

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

Notez la différence de syntaxe : Vite utilise '@components' tandis que TypeScript utilise "@components/*" avec des valeurs de tableau.

Vérifier votre configuration

Testez votre configuration avec une importation :

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

Votre IDE devrait fournir des suggestions d’autocomplétion, et npm run dev devrait démarrer sans erreurs.

Méthode 2 : Configuration automatisée avec vite-tsconfig-paths

Installation et configuration de base

Le plugin vite-tsconfig-paths synchronise automatiquement vos chemins TypeScript avec Vite :

npm install -D vite-tsconfig-paths

Mettez à jour votre configuration 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()]
})

C’est tout. Le plugin lit vos chemins tsconfig.json et configure Vite automatiquement.

Avantages par rapport à la configuration manuelle

• Source unique de vérité : Mettez à jour uniquement tsconfig.json
• Aucune erreur de synchronisation : Les alias correspondent toujours
• Fichiers de configuration plus propres : Moins de code répétitif
• Support des monorepos : Gère les configurations d’espaces de travail complexes

Dépannage des erreurs Vite resolve alias

Projets JavaScript sans TypeScript

Pour les projets JavaScript, créez un jsconfig.json à la place :

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

Le plugin vite-tsconfig-paths fonctionne également avec jsconfig.json.

Monorepos et scénarios avancés

Dans les monorepos, assurez-vous que vos chemins sont relatifs à la racine de l’espace de travail :

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

Pour les utilisateurs Windows, utilisez toujours des barres obliques (/) dans les configurations de chemins—Vite et TypeScript les normalisent correctement.

Divergences entre build et développement

Si les alias fonctionnent en développement mais échouent lors du build :

1. Vérifiez les problèmes de sensibilité à la casse (surtout sur Linux/macOS)
2. Assurez-vous que baseUrl est correctement défini
3. Vérifiez que tous les chemins aliasés existent dans votre sortie de build
4. Vérifiez que votre outil de build préserve la configuration des alias

Référence rapide : Manuel vs vite-tsconfig-paths

Conclusion

Corriger les erreurs Vite Failed to resolve import revient à aligner la résolution des modules entre Vite et TypeScript. La méthode manuelle vous donne un contrôle précis sur les deux configurations, tandis que vite-tsconfig-paths élimine complètement les problèmes de synchronisation.

Pour la plupart des projets, commencez avec vite-tsconfig-paths—c’est plus simple et évite la dérive de configuration. Passez à la configuration manuelle uniquement lorsque vous avez besoin de stratégies d’aliasing différentes entre développement et production, ou lorsque vous travaillez avec des configurations de build inhabituelles nécessitant une logique de résolution personnalisée.

FAQ

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.