Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 38 ยท Build and Optimization

The Production Build

How vite build works: Rollup bundling, hashed file names, outDir, base, minification, source maps, preview, and the build options you will touch most often.

In development Vite serves your source files as native ES modules, one request per module. That is fast to start, but it is not what you want to ship: hundreds of small requests, unminified code and no cache-busting file names. For production, vite build bundles everything with Rollup, minifies it, splits it into chunks and writes the result to a dist folder.

This lesson explains what the build does, what the output looks like, and the options you will use in almost every project. Vite is not available in our runners, so config snippets are real and read-only, and the runnable blocks are stand-ins that demonstrate the ideas (content hashes, manifest, base paths).

The commands

Terminal
vite build      # production build into dist/
vite preview    # serve dist/ locally to test it

A project made from a Vite template has these as npm run build and npm run preview. vite preview is not a production server. It is a convenient static server for checking that the build works before you deploy.

What the output looks like

For a small app, dist/ contains:

Text
dist/
  index.html
  assets/
    index-B8k3Qp1x.js
    index-D2f9aT0c.css
    logo-Cq81mZ3a.svg

Three things happened:

  1. index.html was processed: the dev <script type="module" src="/src/main.js"> was replaced with the hashed output file, and CSS links were added.
  2. Your JavaScript and everything it imports were bundled, tree-shaken (unused exports removed) and minified.
  3. File names got a content hash. If the file's content changes, the name changes, so browsers and CDNs can cache assets for a year without ever serving stale code. Only index.html must be revalidated.
flowchart LR
  A["index.html (entry)"] --> B["Rollup bundles the module graph"]
  B --> C["Tree-shake and minify"]
  C --> D["Hashed files in dist/assets"]
  A --> E["index.html rewritten with hashed URLs"]

The HTML is the entry point; Vite follows its script and style references.

The options you will touch

JavaScript
// vite.config.js (real Vite, read-only)
import { defineConfig } from 'vite';

export default defineConfig({
  base: '/',                 // public path prefix for assets
  build: {
    outDir: 'dist',          // where to write
    emptyOutDir: true,       // clear the folder first
    assetsDir: 'assets',     // subfolder for JS/CSS/media
    sourcemap: false,        // true | 'hidden' | 'inline'
    minify: 'esbuild',       // 'esbuild' | 'terser' | false
    assetsInlineLimit: 4096, // inline assets smaller than 4 KiB as base64
    chunkSizeWarningLimit: 500, // KiB, only a warning
    rollupOptions: {
      // anything Rollup accepts goes here
    },
  },
});

base matters when the site is not served from the domain root. If you deploy to https://example.com/docs/, set base: '/docs/' so generated URLs start with /docs/assets/.... Use base: './' for a relative build that works from any folder, for example inside a mobile web view.

build.sourcemap controls debugging aids. true writes .map files and a comment that DevTools follows. 'hidden' writes maps without the comment, which suits error reporters such as Sentry that you upload maps to. Be careful: public source maps reveal your original source.

build.minify defaults to esbuild, which is very fast. Terser (install it separately) produces slightly smaller output and has options such as dropping console.log calls:

JavaScript
// real Vite
build: { minify: 'terser', terserOptions: { compress: { drop_console: true } } }

assetsInlineLimit inlines small images and fonts as data: URLs to save requests. Set it to 0 to disable.

Hashes and caching in a stand-in

Vite uses a hash of the chunk content. This stand-in uses a simple string hash to show the idea: same content, same name; any change, new name.

JS Stand-in: content-hashed file names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

That is why hashed assets can be cached "forever": the URL itself identifies the content.

Base paths in a stand-in

JS Stand-in: how base changes asset URLs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A frequent deployment bug is a blank page after deploying to a sub-folder: the HTML loads, but /assets/... 404s because base was left at /.

Environment during the build

vite build runs with mode set to production, so import.meta.env.PROD is true, import.meta.env.DEV is false, and .env.production files are loaded. Unused branches such as if (import.meta.env.DEV) { ... } are removed from the bundle by dead-code elimination.

Checking the result

  1. Run npm run build and read the size table Vite prints (raw and gzip sizes per file).
  2. Run npm run preview and open the site. Test real navigation, a refresh on a deep route and the network tab.
  3. Look for warnings: chunks larger than the limit, dynamic imports that are also static imports, or unresolved assets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which bundler does vite build use under the hood?

    Vite serves native modules in dev but bundles with Rollup for production.
  2. 2. Why do output files have a hash in their names?

    A content hash lets you cache assets for a very long time while guaranteeing updates are fetched.
  3. 3. Your site is deployed at https://example.com/shop/ and shows a blank page. What should you check?

    With base left at '/', the HTML asks for /assets/... which does not exist under /shop/.
  4. 4. Is vite preview suitable as a production web server?

    vite preview is a convenience static server. Deploy dist/ to a real static host or CDN.

Summary

  • vite build bundles with Rollup, tree-shakes, minifies and writes hashed files to dist/.
  • index.html is the entry; it is rewritten to point at the hashed assets.
  • Key options: base, build.outDir, sourcemap, minify, assetsInlineLimit.
  • Use vite preview to test, not to serve.
  • Content hashes allow immutable caching; only the HTML needs revalidation.

Next: Code Splitting and Chunks