vite-proxy-folder-name-conflict

Vite Proxy Folder Name Conflict

Problem

Frontend JavaScript/JSX files return 404 errors even though they exist on disk. The browser console shows errors like:

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)

The files exist at paths like src/client/api/hooks/usePeople.js, but Vite returns 404 or serves HTML instead of JavaScript.

Context / Trigger Conditions

This issue occurs when ALL of these conditions are true:

1. Vite dev server with proxy configuration in vite.config.js:

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

2. Client-side folder with the same name as the proxy path:

   src/client/
   ├── api/           ← Folder name matches proxy path "/api"
   │   ├── client.js
   │   └── hooks/
   │       ├── usePeople.js
   │       └── useMedia.js
   

3. Imports that resolve to the proxied path:

   // In src/client/pages/Directory.jsx
   import { usePeople } from '../api/hooks/usePeople.js';
   // Vite transforms this to: /api/hooks/usePeople.js
   // This matches the proxy rule and gets sent to backend!
   

Root Cause

Vite's module resolution transforms relative imports to absolute paths. When you import ../api/hooks/usePeople.js from a page, Vite resolves it to /api/hooks/usePeople.js.

The proxy configuration matches paths starting with /api and forwards them to the backend server. Since /api/hooks/usePeople.js starts with /api, it gets proxied to the backend instead of being served as a static file.

The backend doesn't have a route for /api/hooks/usePeople.js, so it returns 404.

Solution

Option 1: Rename the client folder (Recommended)

Rename the conflicting folder to something that won't match the proxy path:

# Rename api to services (or lib, helpers, etc.)
mv src/client/api src/client/services

# Update all imports
find src/client -name "*.jsx" -o -name "*.js" | xargs sed -i '' 's|from.*['"'"'"]\.\.\/api|from "../services|g'