The Vite build works in preview but dist/index.html shows nothing
Blank white page when double-clicking dist/index.htmlShort 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.
Fix it fast
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.html2Match what you see, then jump to its fix
- 1
The page is blank only when opened by file path, while the preview URL worksdist was opened from disk instead of being servedFix - 2
The 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
The 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
- 1
What does the error look like?
Blank white page when double-clicking dist/index.htmlnpm run preview works on http://localhost:4173 but the file does notAssets 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.html2Fix
Build first, then serve the output with vite preview instead of opening the file.
npm run build
npm run preview3Verify
Open the address the command prints. The default is http://localhost:4173.
curl -I http://localhost:4173Confirmed by vite.dev
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 dist2Fix
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 80803Verify
The page loads on the port you chose.
curl -I http://localhost:8080Confirmed by vite.dev
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.htmlConfirmed by vite.dev
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 fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix