Understanding Vite’s File Structure: Why index.html Belongs at the Root

When working with Vite, a common gotcha is the location of the index.html file. Unlike traditional build tools like Webpack, Vite requires your index.html to reside in the project root directory, not in a public directory.

What happens when index.html is in public? You get HTTP ERROR 404, indicative of a running server but the resource not found:

This localhost page can’t be found
No webpage was found for the web address: http://localhost:5173/
HTTP ERROR 404

Why Does Vite Require This?

Vite uses index.html as an entry point to optimize and bundle your project. Placing it at the root allows Vite to:
• Detect and handle linked assets (e.g., JS, CSS) efficiently.
• Inline scripts and styles directly during development.
• Provide accurate paths for module resolution.

The Correct Structure

Here’s the expected structure for a basic Vite project:

my-project/
├── index.html      // Root-level entry point
├── src/            // Source files (components, styles, etc.)
│   └── main.js
├── public/         // Static assets (not processed by Vite)
│   └── favicon.ico
└── vite.config.js