skip to content

What does the `vite preview` command serve, how do Vite's `preview` options relate to `server` options, and why isn't it a production server?

level: juniorimportance: should knowfreq 14%

answer

  1. serves files already built
  2. build directory, dist by default
  3. port 4173 by default
  4. most options fall back to server.*
  5. docs: not for production

basics

~20 s

vite preview serves the existing build output (dist by default) on port 4173 and builds nothing. Most preview options fall back to server ones, though not the port. Vite's docs call it a local check, not a production server.

solid answer

~40 s

`vite preview` starts a small static server in the build directory (`build.outDir`, `dist` by default), so run `vite build` first or you are looking at a stale build. It listens on `preview.port`, which defaults to `4173` rather than inheriting `server.port`. `preview.host`, `strictPort`, `https`, `open`, `proxy`, `cors` and `allowedHosts` default to the matching `server.*` value, so a dev proxy for `/api` also works in preview unless you set `preview.proxy`. With the default `appType: 'spa'`, unknown paths fall back to `index.html`. A function-form config runs with `command: 'serve'` and `isPreview: true`. Vite's docs say it is for previewing the build locally and is not designed as a production server; hosting belongs to a static host or a server you configure for it.

go deeper

for a junior

Recall that vite preview serves the dist folder that vite build produced, on port 4173, and that it is only for checking a build locally.

for a middle

Explain which preview options fall back to server options, why a dev proxy also applies in preview, and how appType spa makes deep links work.

for a senior

Show you can diagnose a preview that 404s its assets by comparing the build's base and mode with the preview's, and why stale dist folders mislead.

for a principal

Discuss what a production host must decide that preview never does, and how a team should use preview in CI as a smoke check rather than a hosting choice.

## What `vite preview` is for `vite preview` answers one question: **does the built app work when it is served as files?** It starts a small static server in the build directory - `dist` by default, or whatever `build.outDir` or `--outDir` names - and serves the files exactly as `vite build` wrote them. It does not build, transform or hot-update anything. The usual sequence: 1. `vite build` writes the production output (add `--mode staging` for a staging build). 2. `vite preview` serves that output, by default at `http://localhost:4173`. 3. You click through the app, watch the network panel for 404s and compare with what the dev server showed. Skip step 1, or edit sources between the two steps, and you are previewing the previous build. ## Which options it reads Preview has its own `preview` block in the config. Most entries fall back to the dev server's setting when you leave them unset: | Option | Default | |---|---| | `preview.port` | `4173` - its own default, not `server.port` | | `preview.strictPort` | `server.strictPort` | | `preview.host` | `server.host` | | `preview.https` | `server.https` | | `preview.open` | `server.open` | | `preview.proxy` | `server.proxy` | | `preview.cors` | `server.cors` | | `preview.allowedHosts` | `server.allowedHosts` | | `preview.headers` | the response headers you list | The fallback people miss is the proxy: a `/api` rule written for development also proxies in preview unless `preview.proxy` replaces it. If the port is taken, preview tries the next free one unless `strictPort` is set. CLI flags such as `--port`, `--host`, `--base`, `--outDir` and `--mode` override the file. The config file itself loads as usual. A function-form config receives `command: 'serve'` with `isPreview: true`, so a branch on `command === 'serve'` alone also configures the preview; check `isPreview` when the two must differ. With the default `appType: 'spa'`, preview falls back to `index.html` for unknown paths so client-side routes load; `'mpa'` keeps only the non-SPA HTML handling and `'custom'` adds none. ## How it differs from the dev server - **Built files, not source.** The dev server transforms modules when the browser asks for them; preview serves the hashed, minified output from disk. - **No hot updates.** Any change needs another `vite build`. - **No restart on config edits.** The preview server never restarts; stop it and start it again. - **A different default port**, `4173`, so the dev server and the preview can run side by side. ## Why it is not a production server Vite's docs say it plainly: `vite preview` is for previewing the build locally, and it is **not designed as a production server**. It is a convenience check before you deploy. A production host is where you decide caching rules for hashed and unhashed files, compression, TLS, security headers, logging and scaling, and preview does not set out to cover those. Deploy the `dist` folder to a static host, a CDN or a server configured for the job, and use preview only to check what you are about to ship. ## Using it as a smoke check in CI Preview is also the cheapest way to run browser tests against the real build output. A pipeline step can run `vite build --mode staging`, then start `vite preview --mode staging --port 4173 --strictPort` in the background and point the test runner at `http://localhost:4173`. Two flags earn their place: - `--strictPort` makes a port collision fail the job instead of letting preview move to the next port, where the tests would never find it; - `--host` (or `preview.host`) listens on all addresses, which a test browser in another container needs. Stop the preview process when the tests finish; it is a local server, not a deployment. ## What to check when preview misbehaves - **Pages without scripts or styles:** the `base` the build used differs from the one preview serves under - run preview with the same `--mode` or `--base` that the build used. - **Old behaviour:** `dist` is stale; rebuild before previewing. - **`/api` calls going somewhere unexpected:** preview inherited `server.proxy`. - **The wrong port in a script:** preview defaults to `4173`, not to `server.port`. ## What interviewers listen for - That preview serves an existing build and never builds. - That it shares most of its settings with `server.*` by fallback, with the port as the notable exception. - That "not a production server" comes from the tool's own documentation, and why a real host is still needed.

  • Why can a Vite build made with `--mode staging` and a mode-dependent `base` lose its styles under `vite preview`?
    Preview loads the same config file. If `base` is derived from the mode and `vite preview` runs without the `--mode staging` the build used, the config computes a different `base`: the HTML references `/staging/assets/...` while preview serves under `/`, and every asset 404s. Run `vite preview --mode staging`, or pass the same `--base`, so the server and the files agree.
  • How does `vite preview` handle a deep link such as `/jobs/42` in a single-page app?
    With the default `appType: 'spa'`, preview answers unknown paths with `index.html`, so the client-side router can render `/jobs/42`. Under `appType: 'mpa'` that fallback is gone and only real HTML files are served, and `'custom'` adds no HTML handling at all, so a deep link that maps to no file fails.

  • vite preview builds the project before it starts serving
  • vite preview listens on server.port unless told otherwise
  • Preview options never fall back to the server settings
  • vite preview is fine as the production web server
  • Preview hot-updates modules just like the dev server