How to Perform a Vite Build for Production with Vue 3: A Complete Guide

To perform a vite build for production with Vue 3, scaffold your project with the official template, configure vite.config.js to include @vitejs/plugin-vue, run the vite build command, and deploy the resulting dist/ directory to any static hosting service.

Deploying a Vue 3 application requires a reliable production bundle that optimizes assets and handles module resolution correctly. When using Vite, the build process leverages Rolldown (a Rollup-compatible bundler) to transform your source code into static assets ready for deployment. This guide explains the essential steps to configure and execute a vite build for production, referencing the exact implementation details found in the vitejs/vite repository.

Prerequisites and Project Setup

Before running a production build, ensure your project structure follows Vite's conventions. The official create-vite template for Vue provides the necessary foundation, including the dependency declarations found in packages/create-vite/template-vue/package.json and the configuration patterns in packages/create-vite/template-vue/vite.config.js.

To initialize a new project:

npm create vite@latest my-vue-app -- --template vue
cd my-vue-app
npm install

The generated vite.config.js automatically imports and registers the Vue plugin:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})

Understanding the Vite Build Architecture

When you execute vite build, Vite initiates a multi-step compilation process. According to the documentation in docs/guide/build.md, this command produces an application bundle suitable for static hosting services.

The build architecture follows this workflow:

1. Entry Resolution: Vite resolves the default entry point at <root>/index.html, scanning for script tags and module references.
2. Plugin Transformation: The @vitejs/plugin-vue transforms Single File Components (.vue files) into JavaScript, extracts scoped CSS, and handles template compilation.
3. Bundling with Rolldown: Vite uses Rolldown (a fast Rollup-compatible bundler) to tree-shake and bundle modules. You can customize build-time behavior via build.rolldownOptions in your configuration.
4. Asset Output: The process emits hashed static assets to the dist/ directory, including optimized JavaScript, CSS, and the modified index.html.

Configuring the Build for Production

While default settings suffice for basic deployments, production applications often require specific adjustments for public paths, legacy browser support, and environment variables.

Setting the Public Base Path

If deploying to a subdirectory (such as GitHub Pages), configure the base option to ensure asset URLs resolve correctly. In vite.config.js:

export default defineConfig({
  base: '/my-app/',
  plugins: [vue()],
})

Alternatively, pass the base path via CLI:

vite build --base=/my-app/

This setting rewrites all asset references and populates import.meta.env.BASE_URL for runtime URL construction, as implemented in the build pipeline.

Supporting Legacy Browsers

For compatibility with older browsers, install the official legacy plugin:

npm i -D @vitejs/plugin-legacy

Then configure it in vite.config.js:

import legacy from '@vitejs/plugin-legacy'

export default defineConfig({
  plugins: [
    vue(),
    legacy({ targets: ['defaults', 'not IE 11'] })
  ],
})

The legacy plugin automatically generates additional chunks containing polyfills and fallback bundles, as documented in docs/guide/build.md.

Environment Variable Handling

During the build process, Vite statically replaces import.meta.env.BASE_URL with your configured base path. This allows runtime code to construct URLs dynamically without hardcoding deployment paths.

Executing the Production Build

With configuration in place, generate the production bundle by running:

npm run build

This executes vite build, which outputs a report similar to:

building for production...
dist/assets/index-abc123.js   12.3 kB │ gzip: 4.5 kB
dist/assets/style-abc123.css  4.8 kB  │ gzip: 1.2 kB
dist/index.html               0.5 kB

All files in the dist/ directory are optimized, hashed for cache-busting, and ready for deployment.

Previewing and Deploying

Before deploying to production, verify the build locally using the preview server:

npm run preview

This runs vite preview, which serves the contents of dist/ on a local server to validate functionality.

For deployment, copy the entire dist/ folder to any static hosting provider (Netlify, Vercel, Cloudflare Pages, or traditional servers). The output requires no server-side runtime; it consists entirely of static HTML, CSS, and JavaScript assets.

Summary

• Scaffold your project using the official Vue template from create-vite to ensure correct dependency structure in packages/create-vite/template-vue/.
• Configure vite.config.js with @vitejs/plugin-vue and optional settings like base or legacy plugins.
• Execute vite build to trigger Rolldown bundling and generate the dist/ output directory.
• Verify the production build locally using vite preview before deployment.
• Deploy the static dist/ folder to any CDN or hosting service capable of serving static files.

Frequently Asked Questions

What is the difference between vite build and vite preview?

The vite build command compiles your Vue 3 application into optimized static assets for production, outputting them to the dist/ directory. The vite preview command serves the already-built dist/ folder locally, allowing you to test the production bundle before deployment without affecting the build process itself.

How do I change the output directory for vite build for production?

By default, Vite outputs production builds to the dist/ directory. You can change this by setting the build.outDir option in vite.config.js:

export default defineConfig({
  build: { outDir: 'build' }
})

This modifies the destination path used during the Rolldown bundling process.

Why are my assets returning 404 errors after deployment?

This typically occurs when the base configuration does not match your deployment path. If hosting under a subdirectory, ensure vite.config.js includes base: '/your-subpath/' or pass --base=/your-subpath/ to the CLI command. This ensures asset URLs in the generated HTML point to the correct locations.

Does Vite support Server-Side Rendering (SSR) for Vue 3 production builds?

Yes, Vite supports SSR through specialized configuration options, though the standard vite build command produces client-side Single Page Applications (SPAs). For SSR deployments, consult the dedicated SSR guide in the Vite documentation to configure server-specific entry points and rendering logic beyond the standard static build process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}