vite-deploy

What you will run into

After shipping to production, users occasionally see a white screen: the page loads blank, the console reports ChunkLoadError, and a refresh or two fixes it. The root cause is a version mismatch in build artifacts — the user's browser still has the old HTML, but the old hashed assets it references were already overwritten by the new release. Vite itself is a good tool: zero-config builds, content-hashed assets, fast. But these deployment details are rarely documented, and hitting the issue once costs hours of debugging. This guide walks through "install vite → build → deploy without white screens" end to end, with every command verified and copy-pasteable (verified 5.4.21 at collection; major-version 8.2.2 build chain fully re-verified 2026-08-31). When to use it:

• Building frontend source into deployable artifacts (npx vite build);
• Debugging occasional white screens after release (ChunkLoadError: old hashed asset 404);
• Wanting content-hashed assets (cache-friendly; changing a file only invalidates what changed).

When not to use it: SSR/server-rendered scenarios (vite is a build tool; pick the mode that matches your project shape).

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

npm installs vite as a devDependency, and npx vite build produces dist/ (index.html + assets/*-<hash>.js/css). Content-hashed assets are naturally cache-friendly, but the wrong publish order causes white screens:

• Version mismatch: old HTML + new assets → old hashed chunk 404 → ChunkLoadError → white screen;
• Correct order: upload new assets first, then update index.html (keep old assets for one release cycle);
• nginx trap: try_files must not swallow static 404s — match real files first, then fall back to index.html; otherwise the white screen is masked as "loaded fine but empty".

Key concepts:

• content hash: file content changes → filename hash changes;
• ChunkLoadError: loading an old hashed chunk 404s (version mismatch);
• dist/: build output directory.

Where it writes: node_modules + package.json (devDependency); build output goes to dist/.

Step by step

Step 1: Install vite

Why: vite is a build-time tool; install it as a devDependency (--save-dev) so it does not pollute production dependencies. Direct npm from mainland China is slow, so specify the npmmirror registry explicitly (verified: 7s to install 12 packages). Needs Node >= 18 (node v22 verified on this machine).

npm install --save-dev vite --registry=https://registry.npmmirror.com

Expected output: vite 8.x installed into node_modules (8.2.2 re-verified 2026-08-31; 5.4.21 verified at collection) After install, confirm:

• node_modules contains vite (8.2.2 re-verified 2026-08-31; 5.4.21 verified at collection);
• npx vite --version runs.

Stuck? How to recover:

• npm slow/timeout → make sure the command includes --registry=https://registry.npmmirror.com;
• Node version → confirm >= 18.

Step 2: Build

Why: npx vite build produces dist/ (index.html + assets/*-<hash>.js/css). Content hash: changing a file only updates what changed, cache-friendly.

npx vite build

Expected output: dist/ produced with index.html + assets/*-<hash>.js/css (content hash) After install, confirm:

• dist/ exists and assets/ filenames carry hashes;
• build log has no errors.

Stuck? How to recover:

• build error → locate it from the log (dependency/syntax/path), reproduce locally with dev mode (vite dev) before fixing.

Step 3: Deploy without white screens

Why: an occasional white screen after release = the user opens old HTML (cached) whose old hashed chunk was already overwritten → 404 → ChunkLoadError. Three rules: assets before entry; keep old assets for one release cycle; nginx try_files must not swallow static 404s (match real files first, then fall back to index.html).

# Publish order: 1) upload assets/*-<hash>.*  2) then update index.html (keep old assets for one release cycle)
# nginx: try_files matches real static files first, then falls back to index.html (must not swallow 404s)

Expected output: after deployment, old users no longer see white screens on refresh (full solution: site docs) After install, confirm:

• after the new deploy, old pages refresh to the new entry (or at least do not 404 into a white screen).

Stuck? How to recover:

• still white screen → open the browser console and look at the exact 404 chunk filename, compare with the release batch to confirm version mismatch;
• nginx fallback swallowed the 404 → fix the try_files order (real files before index.html).

How to confirm it works

One command plus one check settles it immediately:

npx vite build

Expected output: build succeeds, dist/ produced with index.html + assets/*-<hash>.js/css

• Build artifacts have content-hashed filenames under assets/ (e.g. index-a1b2c3.js);
• After deploy: upload assets/ first, then update index.html; old users refresh without white screens (ChunkLoadError gone);
• Reproduce to verify: temporarily break the old hash filename referenced in index.html; a refresh should show 404/ChunkLoadError (proving the version-mismatch mechanism) — full reproduction local repro log 2026-08-29.

Other environments

• Node version: >= 18 required (node v22 verified here); older Node fails or warns when installing vite 5.
• npm registry: mainland direct is slow; explicit --registry=https://registry.npmmirror.com (verified: 7s to install 12 packages).
• Deploy platform: nginx needs try_files with real files before index.html; pure static hosts (GitHub Pages etc.) publish per-file naturally, but still follow "assets before entry".
• CI environment: build hashes differ every time; keeping one release cycle of cache is enough, no manual CDN purge needed (content hashes invalidate old files automatically).
• SSR projects: vite's build mode differs (SSR needs build.ssr); this entry only covers plain static SPA deployment.

Daily usage

Startup and entry

• Build: npx vite build;
• Local dev: npx vite dev (verified; see Operation 2);
• Preview artifacts: npx vite preview (verified; see Operation 3).

Common operations

Operation 1: Build artifacts

npx vite build

Expected output: dist/ produced with index.html + assets/*-<hash>.js/css (content hash; verified v8.2.2: built in 38ms, dist/assets/index-DaJps1dT.js) Operation 2: Local dev server (changes apply immediately)

npx vite dev --host 0.0.0.0 --port 5173

Expected output: VITE v8.2.2 ready in ~200 ms + Local: http://localhost:5173/ (verified 2026-09-01: port 25173 fixed successfully, page HTML has /@vite/client injected; after editing src/main.js the log shows page reload src/main.js and the browser auto-refreshes) Note (verified pitfall): with a loopback host (localhost / 127.0.0.1), vite 8.2.2 ignores the fixed port and picks a random one - verified: --host 127.0.0.1 --port 25273 actually listened on a random port. To pin a port use --host 0.0.0.0 --port <port> (also reachable from LAN devices; for local-only use, still visit localhost). Operation 3: Preview built artifacts (serves dist/ without rebuilding)

npx vite preview --host 0.0.0.0 --port 4173

Expected output: Local: http://localhost:4173/, serving the dist/ output (verified 2026-09-01: port 24173 fixed, curl returned the same page as the build output; use it before deploy to simulate production and catch white-screen/path issues)

Data and directories

• Output: dist/ (index.html + assets/);
• Dependencies: node_modules + package.json (devDependency).

Uninstall & cleanup

note: npm uninstall as devDependency; clean dist/ build output as needed

npm uninstall vite

Expected output: vite removed from node_modules/package.json

Dependency warnings

• Version: [5.0, 8.2] range (5.4.21 verified at collection; 2026-08-31 major-version 8.2.2 build chain fully re-verified: install + CLI + build + hashed-asset references all consistent, evidence）. Content hashing and the no-white-screen conclusions are version-independent and hold on 8.2.2.
• Environment: Node >= 18 + npm (node v22 verified here).
• Network: npm via npmmirror registry (verified: 7s to install 12 packages).
• Write surface: node_modules + package.json; build output dist/.
• Deploy: assets before entry; keep old assets for one release cycle; nginx try_files must not swallow static 404s.
• Co-install: with playwright-mcp judged possible-compatible (deploy writes build artifacts, verification writes browser state; write surfaces do not overlap); combo "web deploy verification": site docs.

FAQ

• Q: Occasional white screen after release? A: ChunkLoadError = old HTML + new assets version mismatch → old hashed chunk 404. Publish assets before entry and keep old assets for one release cycle; nginx try_files matches real files before falling back to index.html. Full solution: problem entry site docs.
• Q: What is the build hash? A: content hash — file content changes → filename changes, cache-friendly; changing a file only invalidates what changed.
• Q: npm install fails? A: use the npmmirror registry (verified: 7s to install 12 packages); confirm Node >= 18.
• Q: Use with playwright-mcp? A: judged possible-compatible — deploy (build artifacts) and verification (browser) write surfaces do not overlap; combo "web deploy verification": site docs.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.