The connection between
index.html and
main.jsx in a Vite + React project is established through the script tag with the type module attribute pointing to the source file. If this link breaks, you will see a blank white screen or a 404 error for the entry point. This guide walks you through verifying your directory structure, correcting import paths, and ensuring your Vite configuration correctly resolves these modules to restore your application.
Verifying the Directory Structure
The most common cause for this issue is a mismatch between where
index.html resides and where
main.jsx is located. Vite uses the location of
index.html as the root for all relative imports. If your
main.jsx file is not in the same directory or a subdirectory accessible from
index.html, the browser cannot fetch it.
Check your project root. You should have
index.html at the top level. Inside your
src folder, you should have
main.jsx (or
main.tsx). The standard convention places
index.html in the root and
main.jsx inside
src. If you moved
main.jsx to a different folder, you must update the path in
index.html accordingly.
If you are using a monorepo structure, ensure that
index.html is not buried deep within a nested package without proper aliasing. Vite expects the entry point to be easily reachable. A simple check is to open your browser's developer tools, go to the Network tab, and reload the page. Look for a red status code next to
main.jsx or its bundled output. If it shows a 404, the path is definitely wrong.
For more details on how Vite handles TypeScript configuration which often accompanies JSX files, you might find
Understanding the Purpose of tsconfig.node.json in a Vite Project with React and TypeScript helpful, as misconfigured types can sometimes lead to build failures that mask import issues.
Checking the Script Tag Configuration
Open
index.html and locate the script tag that loads your JavaScript. It should look like this:
<script type="module" src="/src/main.jsx"></script>
Notice the leading slash
/. In Vite, the public directory is served from the root. Therefore,
/src/main.jsx tells the server to look for the file in the
src folder relative to the project root. Common mistakes include missing the leading slash, such as writing
src="src/main.jsx" instead of
src="/src/main.jsx". While some bundlers handle relative paths differently, Vite strictly adheres to the root-relative path for clarity and consistency.
Another frequent error is using the wrong extension. If your file is named
main.tsx, you must reference
main.tsx in the HTML. Do not guess the extension. Also, ensure there are no typos in the filename itself. Case sensitivity matters on Linux and macOS servers. If your file is
Main.jsx but you reference
main.jsx, it will fail on case-sensitive file systems.
Inspecting main.jsx Imports
Even if
index.html points to
main.jsx correctly, errors inside
main.jsx can prevent the app from rendering. Open
main.jsx and check the first few lines. You likely have imports like:
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
Ensure that
React and
ReactDOM are installed in your
package.json. Run
npm install react react-dom if they are missing. Then, verify that
./App resolves to an actual file, typically
./App.jsx or
./App.tsx. Vite allows omitting extensions in imports, but only if the file exists exactly as specified.
If you see a syntax error or a module resolution failure in the console, fix those first. A broken
main.jsx will result in a blank page, which users often mistake for a connection issue between HTML and JS. Clearing your browser cache after making changes can also help, as older cached versions of the bundle might persist.
Validating Vite Configuration
Sometimes the issue lies in
vite.config.js. Check if you have defined any custom aliases or base paths. If you set
base: '/my-app/', then your script tag in
index.html must reflect this prefix. However, for most projects, leaving
base as
'/' is sufficient.
Also, ensure that your
package.json scripts are correct. The development command should be
vite. Running
vite starts the dev server and watches for changes. If you are building for production, use
vite build. During the build process, Vite bundles
main.jsx into a single file. If the build fails, check the terminal output for specific module errors.
If you encounter complex UI component errors while troubleshooting, such as those related to form inputs, reading about
Fix TypeScript Error in Single Function onChange Input with Material-UI Slider can provide insight into handling state and events correctly in your React components, which may be failing silently if the initial render doesn't connect properly.
Clearing Cache and Restarting
Vite caches compiled modules in the
.vite directory. Corrupted cache data can lead to stale references. Delete the
.vite folder and the
node_modules/.vite folder if present. Then, restart your development server by stopping the current process and running
npm run dev again.
This forces Vite to re-analyze your dependencies and rebuild the module graph. Often, this simple step resolves mysterious connection issues that persist despite correct file paths. Always restart the server after changing configuration files or adding new dependencies.
Frequently Asked Questions
Why do I see a blank white screen?
A blank screen usually means the JavaScript failed to execute or threw an uncaught exception during initialization. Check the browser console for errors. If the console is empty, the HTML loaded but the script did not run, indicating a path issue. If there are errors, they will tell you exactly which module failed to resolve.
Can I use a relative path like ./main.jsx in index.html?
No, you should always use an absolute path starting with
/ for the script src in Vite. Relative paths can break when the HTML is served from different contexts or when the base URL changes. Using
/src/main.jsx ensures the request goes to the correct root endpoint regardless of where the HTML file sits.
What if my file is named main.tsx instead of main.jsx?
You must update the script tag in
index.html to match the exact filename. Change
src="/src/main.jsx" to
src="/src/main.tsx". Vite handles TypeScript transpilation automatically, so you don't need to change the extension in the HTML yourself, just reference the correct file name.
How do I know if Vite is serving my files correctly?
Open the network tab in your browser developer tools. Reload the page and look for requests to
/src/main.jsx. If you see a 200 OK status, Vite is serving the file. If you see a 404 Not Found, the path is incorrect or the file does not exist in the expected location.