Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท Build and Optimization

Build Targets and Browser Support

Choose which browsers your Vite app supports: the default baseline target, build.target, esbuild syntax lowering, polyfills, plugin-legacy and CSS targets.

Every JavaScript feature you use has a minimum browser version. If your output uses syntax a visitor's browser does not understand, the whole page fails with a syntax error and a white screen. The build target is the promise Vite makes about this: "the code I emit only uses syntax that these browsers support". A lower target means more compatibility but larger, slower code; a higher target means smaller output.

This lesson explains Vite's default target, how to change it, how syntax lowering differs from polyfills, and when to use the legacy plugin. Config is real and read-only. The runnable blocks are stand-ins.

The default target

By default Vite targets browsers that support native ES modules, native dynamic import and import.meta, a set called "baseline widely available" in recent Vite versions (older releases called it modules). In practice that means roughly the last few years of Chrome, Edge, Firefox and Safari. It excludes Internet Explorer and very old mobile browsers.

This default is deliberate: modern syntax such as ?., ??, classes and async/await can be shipped untouched, producing the smallest and fastest code. Most new projects keep it.

Changing build.target

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

export default defineConfig({
  build: {
    target: 'es2020',                      // an ECMAScript version
    // target: ['chrome87', 'safari14'],   // or explicit browsers
    // target: 'esnext',                   // no lowering at all
  },
});

Under the hood, esbuild lowers newer syntax to the target. For example, with target: 'es2019' the optional chaining a?.b becomes a === null || a === void 0 ? void 0 : a.b. If you lower the target, expect slightly larger bundles.

Two different things are easy to confuse:

Syntax lowering Polyfills
What Rewrites a ?? b, class fields, etc. Adds missing APIs such as Promise.allSettled, Array.prototype.at
Who does it esbuild (build.target) Not done by Vite core; use @vitejs/plugin-legacy or add core-js yourself
Failure if missing Syntax error, page does not run TypeError: x is not a function at runtime

Vite's build target does not add polyfills. If you call a new API in an old browser, you must polyfill it yourself.

A feature table as a stand-in

This stand-in shows the decision logic: given the minimum browser versions you must support, which syntax features would need lowering? The version data here is simplified for teaching, not authoritative; always check a real compatibility source.

JS Stand-in: does my syntax need lowering?

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

No output.

The same idea drives tools like Browserslist: from your list of browsers, compute the set of features that cannot be shipped as written.

Browserslist and Vite

Vite does not read .browserslistrc for build.target; it uses build.target directly. The legacy plugin, however, does use Browserslist-style targets. Keep one source of truth: if you also use autoprefixer or other PostCSS tools that read Browserslist, set build.target to match.

CSS targets

CSS has a separate setting, build.cssTarget, which defaults to build.target. It matters for features such as rgba() with spaces or modern color functions that esbuild may rewrite. Set it separately only for an unusual case, such as an Android WebView that supports modern JS but old CSS.

JavaScript
// real Vite
build: { target: 'es2022', cssTarget: 'chrome61' }

@vitejs/plugin-legacy for really old browsers

When you must support browsers that lack native ES modules (for example some old embedded browsers), the legacy plugin builds a second set of bundles in the old SystemJS format, adds polyfills chosen from your targets, and emits both sets in the HTML:

HTML
<!-- simplified output -->
<script type="module" src="/assets/index-a1b2.js"></script>
<script nomodule src="/assets/polyfills-legacy-c3d4.js"></script>
<script nomodule data-src="/assets/index-legacy-e5f6.js" id="vite-legacy-entry"></script>

Modern browsers load only the type="module" script and ignore nomodule; old browsers do the opposite. Most users pay nothing; the build gets slower and bigger.

JavaScript
// real Vite
import legacy from '@vitejs/plugin-legacy';
export default defineConfig({
  plugins: [legacy({ targets: ['> 0.5%', 'not dead'] })],
});
JS Stand-in: module / nomodule selection

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

No output.

How to choose

  1. Look at your real analytics: which browsers do your visitors use?
  2. Keep the default target unless you have a concrete requirement.
  3. If a requirement exists, lower build.target first (cheap).
  4. Add polyfills only for APIs you actually call.
  5. Reach for plugin-legacy only for browsers without module support, and test them on a real device or service.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does build.target control?

    Syntax newer than the target is lowered by esbuild; syntax within the target is kept.
  2. 2. A user on an old browser sees 'x is not a function' for Array.prototype.at. What is missing?

    Target lowering handles syntax. Missing APIs need polyfills, for example through plugin-legacy or core-js.
  3. 3. How does a browser decide between the modern and legacy bundle?

    Browsers with module support ignore nomodule scripts, and older browsers ignore unknown type=module scripts.
  4. 4. What is the best first step when you must support somewhat older browsers?

    Lowering the target is the cheapest option; legacy builds are for browsers without module support.

Summary

  • The default target assumes modern browsers with native ES modules and emits compact modern code.
  • build.target makes esbuild lower syntax; it does not add polyfills.
  • build.cssTarget handles CSS separately.
  • @vitejs/plugin-legacy adds a nomodule SystemJS bundle plus polyfills for old browsers at a cost in build time and size.
  • Decide from real analytics, not guesses.

Next: Library Mode