TypeScript icon, indicating that this package has built-in type declarations

2.1.0 • Public • Published


Easily generate a legacy bundle for outdated browser support.


  • Based on @babel/preset-env
    Easily customize which browsers you want to support (via the targets option).

  • Automatic feature detection
    The injected <script> that decides which bundle to load will check whether ES modules (eg: import) and the expected JavaScript version (determined by esbuildTarget in your Vite config) are supported by the user's browser. If not, the legacy bundle is loaded instead!

  • Hassle-free polyfills
    With the help of, you can add polyfills without npm install. Just add "InteractionObserver" to the polyfills array, and the legacy bundle will automatically load it. Learn more

  • Usage-based core-js@3 inlining
    When corejs: true is passed, modern features are detected by Babel, and only the necessary core-js polyfills are embedded in the legacy bundle.

  • Sourcemap support
    Set sourcemap: true in your Vite config to easily debug your production bundles.

  • Minify support
    When minify is truthy in your Vite config, the legacy bundle (which includes any core-js polyfills) is minified with terser. Customize the minifier via the terserOption in your Vite config.

  • Production only
    The legacy bundle is only generated when vite build runs, because Vite never bundles during development (that's the whole point of Vite).



import legacyPlugin from 'vite-plugin-legacy'

export default {
  plugins: [
    // The default options are listed below. Pass nothing to use them.
      // The browsers that must be supported by your legacy bundle.
      targets: [
        '> 0.5%',
        'last 2 versions',
        'Firefox ESR',
        'not dead',
      // Define which polyfills your legacy bundle needs. They will be loaded
      // from the server. See the "Polyfills" section for more info.
      polyfills: [
        // Empty by default
      // Toggles whether or not browserslist config sources are used.
      ignoreBrowserslistConfig: false,
      // When true, core-js@3 modules are inlined based on usage.
      // When false, global namespace APIs (eg: Object.entries) are loaded
      // from the server.
      corejs: false,



The polyfills option lets you define which APIs to load from the server. If you're using TypeScript in your Vite config, you'll get auto-completion for all supported polyfills. The list is incomplete, so open an issue if there's a missing polyfill that you need.

Polyfills related to global namespaces (eg: Object.entries) are inferred from the esbuildTarget in your Vite config, which defaults to es2020 if undefined. Be careful not to use an API that your target does not support. For example, don't use Promise.prototype.finally if your target is older than es2018. You can use this tool to know when APIs were introduced.

By default, this plugin does not check if your bundle is using the global namespace APIs before importing their polyfills from If you want that, you can pass corejs: true to the plugin, which only includes the polyfills your legacy bundle needs. The downside of using corejs: true is that polyfills are inlined instead of being loaded separately, which allows for the browser to reuse cached polyfills between websites. Even if you set corejs to true, you can still use the polyfills option if you need APIs not supported by core-js (like IntersectionObserver).

The polyfills option allows any of the values in this list.

Package Sidebar


npm i vite-plugin-legacy

Weekly Downloads






Unpacked Size

26.6 kB

Total Files


Last publish


  • aleclarson