Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 38 ยท Project Structure and Config

Project Structure and index.html

Learn how a Vite project is organized, why index.html is the entry point at the root, how root and base paths work, and how multi-page apps use several HTML files.

A Vite project looks small, and that is deliberate. A handful of folders and files cover almost everything, but each has a specific job, and a few rules (especially around index.html) differ from older tools. Knowing the rules saves you from confusing 404 errors and broken paths after deployment.

Vite is not installed on this site, so project trees and config are read-only. The runnable examples are stand-ins that model path handling in Node.js or the browser.

The standard layout

TEXT
my-app/
โ”œโ”€ index.html          entry point (project root)
โ”œโ”€ package.json
โ”œโ”€ vite.config.js      optional configuration
โ”œโ”€ tsconfig.json       if you use TypeScript
โ”œโ”€ .env                optional environment variables
โ”œโ”€ public/             files copied as-is, served from /
โ”œโ”€ src/                your code
โ”‚  โ”œโ”€ main.js
โ”‚  โ”œโ”€ components/
โ”‚  โ”œโ”€ assets/          images, fonts imported from code
โ”‚  โ””โ”€ styles/
โ”œโ”€ node_modules/       installed packages
โ””โ”€ dist/               build output (generated, not committed)

Only index.html and package.json are truly required. Everything else you add when you need it. The folder name src is a convention, not a rule: Vite follows imports wherever they point.

index.html is the entry

Older bundlers take a JavaScript file as the entry and generate HTML around it. Vite flips this. Your HTML file is the entry, and the script tags inside it are the way into your code. Vite treats the HTML as part of the module graph:

HTML
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" href="/favicon.svg" />
    <link rel="stylesheet" href="/src/styles/main.css" />
    <title>My App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

During a build Vite:

  • finds <script type="module" src> and bundles that file with everything it imports;
  • finds <link rel="stylesheet" href> to local files and processes the CSS;
  • processes URLs in <img src>, <link href> and similar tags, hashing assets it can resolve;
  • writes a new index.html in dist/ with updated, hashed URLs.

Because HTML is an entry, you can keep real content in it, for example static text or SEO tags, and use the script only to enhance it.

Root-relative paths and the project root

A URL that begins with / in your HTML or CSS is resolved against the project root (the folder containing index.html, called root). So /src/main.js means "src/main.js inside the project", not a file at the disk root. For files in public/, the URL has no public in it: public/favicon.svg is requested as /favicon.svg.

Relative URLs (./logo.svg, ../img/a.png) are resolved from the file that contains them, as usual.

This stand-in mirrors the three resolution rules so you can see them side by side. It is a model of the behaviour, not Vite's code.

Node.js Stand-in: how a URL maps to a file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Changing the root

You can point Vite at another folder with root in the config or on the command line:

Terminal
vite ./frontend

With root: 'frontend', index.html is expected at frontend/index.html, and config file lookups still happen from where you ran the command. This is useful in monorepos that hold several apps.

Multi-page apps

A Vite app can have many HTML entries. In development any .html file in the root is served at its path: about.html at /about.html. In a build, only index.html is included unless you list the others:

JavaScript
// vite.config.js
import { resolve } from 'node:path';
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        main: resolve(import.meta.dirname, 'index.html'),
        about: resolve(import.meta.dirname, 'about.html'),
        admin: resolve(import.meta.dirname, 'admin/index.html'),
      },
    },
  },
});

Each entry becomes a page with its own HTML and shares chunks with the others when code is common. Use this for sites with real separate pages. For apps with many routes inside a single page (a single-page app), keep one index.html and a client-side router.

Single-page apps and the fallback

In a single-page app, /users/42 should show the same index.html as /. The Vite dev server already does this by serving index.html for unknown paths (appType: 'spa'). The other values are 'mpa' (multi-page, no fallback) and 'custom' (you handle HTML yourself, as in server-side rendering). In production your host needs the same fallback rule; see the deployment lessons.

What goes where

Where does a file belong?

index.html Entry; lives at the root
src/ Code and assets you import
public/ Copied untouched, served from /
dist/ Generated; never edit it

When in doubt, import it from src.

1 / 2

Files in src that you import get processed, optimized, hashed for long caching and checked at build time (a missing file is an error). Files in public are untouched and not checked. Static Assets and the public Directory covers this in depth.

Common mistakes

  • Putting index.html in public/. It then is not an entry and your scripts are not bundled.
  • Using src/main.js (no leading slash) in the script tag. It works from the root file, but a leading / is clearer and works from nested HTML files too.
  • Expecting new HTML files in dist/. Extra HTML entries need build.rollupOptions.input.
  • Committing dist/ or node_modules/. Add both to .gitignore.

A page that behaves like an entry

This runnable page imitates what a Vite entry does: static HTML in the file, and a module script that attaches behaviour.

HTML-first entry with a module script

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the entry point of a Vite app?

    Vite reads the root index.html and follows its script and link tags into your code.
  2. 2. A file at public/favicon.svg is requested from which URL?

    Files in public are served from the site root, without the public folder name.
  3. 3. How do you include a second HTML page, admin.html, in the production build?

    Only index.html is built by default. Extra entries are listed in build.rollupOptions.input.
  4. 4. Which folder should you never edit by hand?

    dist is the generated build output and is overwritten by every build.

Summary

  • index.html at the project root is Vite's entry; its script and link tags lead to your code.
  • URLs starting with / resolve from the project root, and public/ files are served without the folder name.
  • src/ holds code and imported assets; public/ holds files copied untouched; dist/ is generated output.
  • Multi-page apps list extra HTML files in build.rollupOptions.input.
  • appType: 'spa' makes the dev server fall back to index.html for unknown paths.

Next: The Vite Config File