Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

The Vite build works in preview but dist/index.html shows nothing

ErrorBlank white page when double-clicking dist/index.html

Short answer

A Vite build is made to be served by a web server, not opened from disk. Run npm run build, then npm run preview, which serves dist on port 4173. If the site lives in a sub-folder or must be portable, set base in the Vite config so asset URLs match where the files sit.

  • Applies to Vite 7, Node.js 22, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the built index.html in an editor and read the script and link URLs. A leading slash means the page expects to be served from the site root.

    grep -n "src=\|href=" dist/index.html
  2. 2Match what you see, then jump to its fix

    1. 1The page is blank only when opened by file path, while the preview URL worksdist was opened from disk instead of being servedFix
    2. 2The preview shows an old build, an empty dist folder or nothing at http://localhost:5173You ran the preview before building, or expect the dev portFix
    3. 3The page loads on the root but assets return 404 under a sub-path such as /my-repo/base does not match the folder the site is served fromFix

What does the error look like?

  • Blank white page when double-clicking dist/index.html
  • npm run preview works on http://localhost:4173 but the file does not
  • Assets under /assets/ return 404 after deploying to a sub-path

Cause 1 of 3

dist was opened from disk instead of being served

1Check

The built page is meant for a static web server. The preview command exists to serve the dist folder locally.

ls dist && head -n 20 dist/index.html

2Fix

Build first, then serve the output with vite preview instead of opening the file.

npm run build
npm run preview

3Verify

Open the address the command prints. The default is http://localhost:4173.

curl -I http://localhost:4173

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

You ran the preview before building, or expect the dev port

1Check

Preview serves whatever is in dist, and it listens on 4173, not on the dev server's port.

ls -la dist

2Fix

Rebuild so dist is current, run preview again and use the printed address. Use --port in the script if you need a fixed one.

npm run build
npx vite preview --port 8080

3Verify

The page loads on the port you chose.

curl -I http://localhost:8080

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

base does not match the folder the site is served from

1Check

The default base is /, so built URLs start at the site root. A project site on GitHub Pages lives under /<REPO>/.

grep -n "base" vite.config.*

2Fix

Set base to the sub-path. If you do not know the path in advance, a relative base of ./ makes the generated URLs relative to each file.

// vite.config.ts
export default defineConfig({
  base: '/my-repo/', // or './' when the path is unknown
})

3Verify

Rebuild and check the asset URLs in the output.

npm run build
grep -n "src=" dist/index.html

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Treat npm run preview as the check before every deploy.
  • Set base in the Vite config as soon as the deploy target is a sub-path.
  • Do not use vite preview as the production server, since the docs say it is only for previewing the build.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.