Vite Build Target Decision Guide: ESM vs. Legacy Compatibility

The Decision: How Far Back Must Your Bundle Reach?

When you run vite build, Vite must decide what JavaScript syntax and module format to emit. ES modules (ESM) are the native browser standard for loading JavaScript with <script type="module">. That choice is controlled by build.target and, optionally, the @vitejs/plugin-legacy plugin. Pick esnext and you ship the smallest, fastest bundle for modern browsers, but older engines will crash. Pick es2015 or add the legacy plugin and you gain compatibility at the cost of larger output and slower builds. This guide compares the supported options and shows how to validate which bundle a browser actually loads.

Constraints That Drive the Choice

Before editing configuration, answer three questions:

• Browser matrix: Do you need to support browsers without native ES module support, such as Internet Explorer 11 or older Safari versions?
• Performance budget: Is bundle size or build time a hard constraint, or can you accept a larger dist directory?
• Polyfill ownership: Are you already importing polyfills manually, or do you expect the build tool to inject them?

Supported Options Compared

Option	What it emits	Best for	Primary cost
build.target: 'esnext'	Modern syntax and native ESM	Evergreen browsers, internal tools	Runtime crashes in older engines
build.target: 'es2015'	Transpiled syntax, still ESM	Apps needing broad but not ancient support	Larger bundle, more transpilation
@vitejs/plugin-legacy	Dual bundle: modern ESM plus legacy fallback with polyfills	Public apps that must support browsers lacking native ESM	Longest build time, largest output, potential polyfill conflicts

Trade-offs in Practice

esnext: Speed and Size, With a Hard Floor

Setting build.target to esnext tells esbuild, the bundler Vite uses for production builds, to perform minimal downleveling. The output preserves modern syntax such as optional chaining and nullish coalescing, and ships as ES modules. Because there is less transpilation, the build finishes faster and the resulting files are smaller. The trade-off is absolute: if a browser does not understand that syntax or native module loading, the application will fail at runtime rather than degrade gracefully.

es2015: A Middle Ground

Lowering the target to es2015 instructs esbuild to rewrite newer syntax into ES2015-compatible equivalents. You still emit ES modules, so the browser must support <script type="module">. This is useful when your audience uses browsers that support modules but not the latest syntax proposals. Expect a noticeable increase in bundle size because helper functions and rewritten operators add bytes.

plugin-legacy: The Compatibility Safety Net

The legacy plugin takes a different approach. It generates two sets of assets: a modern bundle for ESM-capable browsers and a legacy fallback bundle for everything else. It injects polyfills for JavaScript features that the legacy bundle requires. Browsers that understand modules load the modern files; browsers that do not fall back to the legacy bundle via the nomodule attribute.

This safety net is expensive. Because Vite runs two compilations, build time increases significantly. The dist folder contains duplicate chunks, so total output size grows. If you already import polyfills in your application code, the plugin's injected polyfills may conflict, causing double-loading or subtle bugs.

Concrete Implementation

The following vite.config.ts shows a conservative configuration that uses es2015 as the primary target and enables the legacy plugin for older browsers. Adjust the targets array to match your actual support matrix.

// vite.config.ts
import { defineConfig } from 'vite'
import legacy from '@vitejs/plugin-legacy'

export default defineConfig({
  build: {
    // Downlevel syntax to ES2015 for the primary bundle
    target: 'es2015',
  },
  plugins: [
    legacy({
      targets: ['defaults', 'not IE 11'],
    }),
  ],
})

Run the build from your project root. You need Node.js installed and the project dependencies already fetched.

# Run in your terminal at the project root
npm run build

# Or, if you invoke Vite directly:
npx vite build

Expected check: After the build completes, inspect the dist directory. If the legacy plugin is active, you should see both modern module files referenced by type="module" scripts and legacy fallback files referenced by nomodule scripts. If you only see one set of assets, the plugin did not run or its configuration excluded all targets.

Risk: The dual-bundle output roughly doubles the number of emitted chunks. If your deployment pipeline has strict size limits or slow upload steps, measure the dist folder size before and after enabling the plugin.

Validating the Result in a Browser

Configuration alone does not prove that the correct bundle loads. Use these checks:

1. Inspect the Network tab. Open your production build in a modern browser. In DevTools, filter by JS. Confirm the browser requests the module script, not the nomodule fallback.
2. Test an older engine. Load the same build in a browser version that lacks native ESM support. The legacy bundle should execute instead. If the page is blank or throws syntax errors, the fallback is not wired correctly.
3. Check for duplicate polyfills. In the Network tab, look for multiple requests to the same polyfill file. If you see duplicates, remove manual polyfill imports and rely on the plugin, or disable the plugin's injection and manage them yourself.

Limitations and Version Sensitivity

Vite's defaults and plugin behavior evolve across major versions. The build.target default and the exact polyfill set injected by @vitejs/plugin-legacy can change. Before committing to a configuration, verify the behavior against the Vite version pinned in your package.json. The guidance above reflects well-established behavior, but you should confirm the current defaults in your project's installed version.

There is no universal "best" target. A documentation site for developers can safely use esnext. A public e-commerce checkout page may need the legacy plugin despite the build cost. The correct choice is the one that matches your actual browser matrix and operational constraints.