# Vite Build Shows a Blank Page — dist/index.html, GitHub Pages and Refresh 404s

Canonical: https://commareports.com/fix/vite-build-blank-page
Published: 2026-11-16

> `npm run dev` works, but the built app is a white screen. The console message that names each cause — absolute /assets paths, module CORS from file://, the wrong base on GitHub Pages, router 404s on refresh, undefined env vars — and the fix for each.

# 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               |

## 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

```html
<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:

```js
// 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'](/fix/cors-error-file-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`](https://github.com/richardtallent/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:

  ```js
  // 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](/tools/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.

```js
// 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/`:

```jsx
// React Router
<BrowserRouter basename={import.meta.env.BASE_URL}>
```

```js
// 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](/fix/gitlab-pages-report-404).

## "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](/fix/s3-html-downloads-instead-of-opening).

## 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_`:

```js
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:

```js
// 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](/share-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 →](https://commareports.com/)**

### Related

- [React (Create React App, webpack) build shows a blank page](/fix/react-build-blank-page)
- [CORS error from origin 'null'](/fix/cors-error-file-origin-null)
- [ERR_FILE_NOT_FOUND in Chrome](/fix/err-file-not-found)
- [GitLab Pages report 404s](/fix/gitlab-pages-report-404)
- [The localhost link doesn't work for others](/fix/localhost-link-doesnt-work-for-others)
- [Share a Vite build](/share-vite-build) · [Share an Angular build](/share-angular-build)
- [Free HTML inliner](/tools/html-inliner)
