Vite build shows a blank page

npm run dev works. npm run build succeeds. Then the built app is a white screen, with no error on the page and the root <div id="app"> empty.

Open the console (F12 → Console) before changing anything. A blank Vite build almost always leaves one message, and the message tells you which of the causes below it is.

Match the console message to the cause

What the console or Network tab shows Cause Fix
Failed to load resource: net::ERR_FILE_NOT_FOUND for /assets/… Opened from disk; absolute asset paths Opened the file directly
…from origin 'null' has been blocked by CORS policy Opened from disk; module script Opened the file directly
404 for https://user.github.io/assets/index-….js Wrong base on a sub-path host Wrong base
Expected a JavaScript module script but the server responded with a MIME type of "text/html" The .js request got index.html back MIME type text/html
Home page fine, any other URL 404 on refresh Server has no SPA fallback Refresh 404
Cannot read properties of undefined near an env var, or process is not defined Variable missing at build time Env vars
Nothing at all, and Elements shows an empty root Router basename doesn't match the URL Wrong base

Check it away from your machine

See your page the way someone else will

Drop the HTML or paste it. It opens on a shareable page, so you can confirm the fix works for a reader, not just on your laptop.

Your file is read in this tab and nothing is uploaded until you publish. Creating an account is free, and reading a shared link never needs one.

You opened dist/index.html from disk

This is the most common one, and it is two problems stacked.

1. Absolute asset paths. By default Vite writes

<script type="module" crossorigin src="/assets/index-B4x9kQ2.js"></script>

On a web server /assets/… means "from the site root". On a file:/// page it means the root of your disk — C:\assets\ or /assets/ — so every file is ERR_FILE_NOT_FOUND.

2. Module scripts use CORS. Change the base to relative paths:

// vite.config.js
export default { base: "./" };

and the paths now resolve — but the entry is still a <script type="module">. Browsers always fetch modules in CORS mode, and a file:// page has the opaque origin null, so Chrome and Edge block it:

Access to script at 'file:///…/dist/assets/index-B4x9kQ2.js' from origin
'null' has been blocked by CORS policy

base: './' alone is not enough. Firefox lets a file load modules from the same folder, which is why "it works on my machine" is sometimes literally true. The full explanation is in CORS error from origin 'null'.

Fixes, in order of effort:

  • Serve it. npx vite preview (after vite build) or npx serve dist gives the folder a real http://localhost origin. Fine for you; useless for the person you send it to.

  • Build one file. vite-plugin-singlefile inlines every chunk and stylesheet into index.html. An inline module has nothing to fetch, so the CORS check never runs, and the result opens from disk, an email attachment or a chat upload:

    // vite.config.js
    import { viteSingleFile } from "vite-plugin-singlefile";
    export default { plugins: [viteSingleFile()] };
    

    Large images and fonts still sit next to it; the free HTML inliner embeds whatever the plugin left out and lists anything it couldn't resolve.

  • Give it a URL. See the last section below.

The site lives under a sub-path

GitHub Pages project sites, GitLab Pages, an S3 prefix and a reverse proxy at /app/ all serve your build from somewhere other than /. With the default base: '/' the page asks for https://user.github.io/assets/… instead of https://user.github.io/repo/assets/…, and gets a 404.

// vite.config.js
export default { base: "/repo/" }; // or "./" if the path isn't fixed

Then tell the router the same thing, or it renders nothing because no route matches /repo/:

// React Router
<BrowserRouter basename={import.meta.env.BASE_URL}>
// Vue Router
createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes });

import.meta.env.BASE_URL always equals the base you built with, so the two can't drift. On GitLab Pages, also check that the job publishes public/ — see GitLab Pages report 404s.

"Expected a JavaScript module script…"

Failed to load module script: Expected a JavaScript module script but the
server responded with a MIME type of "text/html".

The browser asked for a .js file and received an HTML page. Most hosts configured for single-page apps answer any missing path with index.html, so a wrong path comes back as a 200 with HTML instead of a 404. The usual reasons:

  • Wrong base — same as the section above, with a fallback hiding the 404.
  • The project root was deployed, not dist/. The source index.html points at /src/main.tsx, which only the dev server can compile. Check the publish directory in Netlify, Vercel, Cloudflare Pages or your CI step.
  • A stale index.html. A CDN or service worker cached the old entry page, which references hashed files that the new deploy deleted. Hard-reload (Ctrl+Shift+R); if that fixes it, set Cache-Control: no-cache on index.html and long caching only on /assets/*.

If the server returns .js with application/octet-stream or text/plain, the host's MIME table is wrong — the same class of problem as S3 downloading HTML instead of rendering it.

Refresh or a deep link 404s

The home page loads, links inside the app work, but refreshing /settings or opening a shared link to it returns 404. The route only exists in JavaScript; the server looks for a file called settings and has none.

Host Fallback to index.html
GitHub Pages Copy dist/index.html to dist/404.html in the build step
Netlify public/_redirects: /* /index.html 200
Vercel vercel.json: {"rewrites":[{"source":"/(.*)","destination":"/"}]}
Cloudflare Pages Automatic when there is no 404.html at the root
nginx try_files $uri $uri/ /index.html;
S3 / static file host Error document index.html, or switch to hash routing

Where you can't configure the server at all, use hash routing (createHashRouter, createWebHashHistory). URLs look like /#/settings, the server only ever sees /, and refreshes always work.

An environment variable is undefined

Vite replaces import.meta.env.* at build time, and only for names that start with VITE_:

import.meta.env.VITE_API_URL; // baked into the bundle
import.meta.env.API_URL; // undefined, always
process.env.API_URL; // ReferenceError: process is not defined

The classic blank page: .env.local exists on your laptop, the CI build doesn't have it, the value is undefined, and new URL(import.meta.env.VITE_API_URL) throws before the first render. Set the variable in the build environment — not the runtime one, there isn't one — and fail the build early if it's missing:

// vite.config.js
if (!process.env.VITE_API_URL) throw new Error("VITE_API_URL is not set");

process is not defined from a dependency means a package written for Node expects the global; define: { "process.env": {} } in the config is the usual stopgap.

Two more that only show up in the build

  • Case-sensitive imports. import Header from "./header" resolves to Header.tsx on macOS and Windows, then fails on the Linux CI runner. The build usually errors, but a lazy import() can fail only at runtime.
  • A crash during the first render. Without an error boundary, any exception in a top-level component unmounts the whole tree — white screen. Run vite build --mode development --minify false and serve it to get a readable stack trace.

Stop sending the dist folder

Every file-based fix above has a ceiling: the person you send the build to still needs the right folder, the right browser and no CORS surprises. A build preview works best as a URL.

Comma takes the dist/ folder or a zip of it and returns one link. Assets upload alongside the entry page with their references rewritten, so the absolute-path and file:// problems disappear, and reviewers comment on the exact element they mean instead of sending a screenshot. Steps and the API call for CI are in share a Vite build.

Two honest caveats. Reports run in a sandboxed iframe with scripts enabled but no same-origin access, so code that touches localStorage or cookies without a try/catch throws there — guard it. And for path-based routing, build the preview with hash routing so every view has a working link.

Publish a build preview →

Related

Have an HTML report to share? Publish it free and send one link people can comment on.