vite-plugin-legacy

Easily generate a legacy bundle for outdated browser support.

Features

• 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 Polyfill.io, 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).

 

Example

import legacyPlugin from 'vite-plugin-legacy'

export default {
  plugins: [
    // The default options are listed below. Pass nothing to use them.
    legacyPlugin({
      // The browsers that must be supported by your legacy bundle.
      // https://babeljs.io/docs/en/babel-preset-env#targets
      targets: [
        '> 0.5%',
        'last 2 versions',
        'Firefox ESR',
        'not dead',
      ],
      // Define which polyfills your legacy bundle needs. They will be loaded
      // from the Polyfill.io server. See the "Polyfills" section for more info.
      polyfills: [
        // Empty by default
      ],
      // Toggles whether or not browserslist config sources are used.
      // https://babeljs.io/docs/en/babel-preset-env#ignorebrowserslistconfig
      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 Polyfill.io server.
      corejs: false,
    })
  ]
}

 

Polyfills

The polyfills option lets you define which APIs to load from the Polyfill.io 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 Polyfill.io. 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.