Conflit de Nom de Dossier avec Proxy Vite

Problème

Les fichiers JavaScript/JSX frontend retournent des erreurs 404 bien qu'ils existent sur le disque. La console du navigateur affiche des erreurs comme :

usePeople.js:1 Failed to load resource: the server responded with a status of 404 (Not Found)
useMedia.js:1 Failed to load resource: the server responded with a status of 404 (Not Found)

Les fichiers existent à des chemins comme src/client/api/hooks/usePeople.js, mais Vite retourne 404 ou sert du HTML au lieu du JavaScript.

Contexte / Conditions de déclenchement

Ce problème se produit quand TOUTES ces conditions sont réunies :

Serveur de développement Vite avec configuration de proxy dans vite.config.js :

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3001',
      changeOrigin: true,
    },
  },
}

Dossier côté client avec le même nom que le chemin du proxy :

src/client/
├── api/           ← Le nom du dossier correspond au chemin du proxy "/api"
│   ├── client.js
│   └── hooks/
│       ├── usePeople.js
│       └── useMedia.js

Imports qui se résolvent en chemin proxifié :

// Dans src/client/pages/Directory.jsx
import { usePeople } from '../api/hooks/usePeople.js';
// Vite transforme cela en : /api/hooks/usePeople.js
// Cela correspond à la règle de proxy et est envoyé au backend !

Cause racine

La résolution de modules de Vite transforme les imports relatifs en chemins absolus. Quand vous importez ../api/hooks/usePeople.js à partir d'une page, Vite la résout en /api/hooks/usePeople.js.

La configuration du proxy correspond aux chemins commençant par /api et les transmet au serveur backend. Puisque /api/hooks/usePeople.js commence par /api, il est proxifié vers le backend au lieu d'être servi comme fichier statique.

Le backend n'a pas de route pour /api/hooks/usePeople.js, il retourne donc 404.

Solution

Option 1 : Renommer le dossier client (Recommandé)

Renommez le dossier conflictuel en quelque chose qui ne correspondra pas au chemin du proxy :

# Renommez api en services (ou lib, helpers, etc.)
mv src/client/api src/client/services

# Mettez à jour tous les imports
find src/client -name "*.jsx" -o -name "*.js" | xargs sed -i '' 's|from.*['"'"'"]\.\.\/api|from "../services|g'

Option 2 : Utiliser un chemin de proxy différent

Changez le chemin du proxy en quelque chose de plus spécifique :

// vite.config.js
server: {
  proxy: {
    '/api/v1': {  // Chemin plus spécifique
      target: 'http://localhost:3001',
      changeOrigin: true,
    },
  },
}

Option 3 : Configurer le proxy pour exclure certains motifs

Utilisez une fonction personnalisée pour exclure certains chemins :

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3001',
      changeOrigin: true,
      bypass: (req) => {
        // Ne proxifiez pas les requêtes pour les fichiers JS/TS
        if (req.url.match(/\.(js|jsx|ts|tsx|mjs)$/)) {
          return req.url;
        }
      },
    },
  },
}

Vérification

Après avoir appliqué la correction :

Videz le cache de Vite : rm -rf node_modules/.vite
Redémarrez le serveur de développement : npm run dev
Vérifiez la console du navigateur - les erreurs 404 doivent avoir disparu
Vérifiez que l'app se charge et que les appels API fonctionnent toujours

Testez les deux cas :

Servage de fichiers frontend : curl http://localhost:5173/services/hooks/usePeople.js devrait retourner du JavaScript
Proxification d'API : curl http://localhost:5173/api/people devrait retourner du JSON du backend

Exemple

Avant (cassé) :

src/client/
├── api/                    ← Entre en conflit avec le proxy
│   └── hooks/
│       └── usePeople.js
├── pages/
│   └── Directory.jsx       ← import from '../api/hooks/usePeople.js'

vite.config.js:
  proxy: { '/api': 'http://localhost:3001' }

Résultat : Le navigateur reçoit 404 pour usePeople.js

Après (corrigé) :

src/client/
├── services/               ← Renommé pour éviter le conflit
│   └── hooks/
│       └── usePeople.js
├── pages/
│   └── Directory.jsx       ← import from '../services/hooks/usePeople.js'

vite.config.js:
  proxy: { '/api': 'http://localhost:3001' }  ← Inchangé

Résultat : Les fichiers frontend sont servis correctement, l'API est toujours proxifiée

Remarques

Ce problème ne concerne pas seulement React—il affecte tout projet Vite avec des proxies
Noms de dossiers courants en conflit : api, graphql, socket, ws
Le problème se manifeste uniquement en développement (serveur de développement Vite) ; les builds de production n'ont pas ce problème
Si vous utilisez des alias de chemin TypeScript, assurez-vous qu'ils évitent également les conflits avec les chemins de proxy
Videz toujours le cache de Vite (node_modules/.vite) après avoir changé la structure des dossiers

Problèmes associés

Des problèmes similaires peuvent survenir avec d'autres serveurs de développement (webpack-dev-server, Create React App)
Si vous utilisez un monorepo, vérifiez les configurations de proxy à la fois à la racine et au niveau des packages

vite-proxy-folder-name-conflict