What is @vitejs/plugin-legacy?
@vitejs/plugin-legacy is a Vite plugin that provides support for legacy browsers by transpiling modern JavaScript syntax to ES5 and injecting polyfills for missing features. This allows developers to use modern JavaScript features while ensuring compatibility with older browsers.
What are @vitejs/plugin-legacy's main functionalities?
Transpile Modern JavaScript to ES5
This feature allows you to transpile modern JavaScript syntax to ES5, ensuring compatibility with older browsers. The 'targets' option specifies the browsers you want to support.
import legacy from '@vitejs/plugin-legacy';
export default {
plugins: [
legacy({
targets: ['defaults', 'not IE 11']
})
]
};
Inject Polyfills
This feature allows you to inject polyfills for missing features in older browsers. The 'polyfills' option specifies the polyfills you want to include.
import legacy from '@vitejs/plugin-legacy';
export default {
plugins: [
legacy({
polyfills: ['es.promise.finally', 'es/map', 'es/set']
})
]
};
Modern and Legacy Bundle
This feature allows you to create both modern and legacy bundles. The 'modernPolyfills' option ensures that modern browsers get a smaller bundle with only necessary polyfills.
import legacy from '@vitejs/plugin-legacy';
export default {
plugins: [
legacy({
modernPolyfills: true
})
]
};
Other packages similar to @vitejs/plugin-legacy
babel-preset-env
babel-preset-env is a Babel preset that allows you to use the latest JavaScript without needing to micromanage which syntax transforms (and optionally, browser polyfills) are needed by your target environment(s). It is similar to @vitejs/plugin-legacy in that it helps in transpiling modern JavaScript to be compatible with older browsers, but it is more general-purpose and can be used outside of Vite.
core-js
core-js is a modular standard library for JavaScript that includes polyfills for ECMAScript up to 2021, promises, symbols, collections, iterators, and many other features. It is similar to @vitejs/plugin-legacy in that it provides polyfills for missing features in older browsers, but it is a standalone library that can be used with various build tools.
polyfill-library
polyfill-library is a service that provides polyfills for web features based on the user's browser. It is similar to @vitejs/plugin-legacy in that it helps in injecting polyfills for older browsers, but it is a more dynamic solution that serves polyfills based on the actual browser making the request.
@vitejs/plugin-legacy
Note: this plugin requires vite@^2.0.0
.
Vite's default browser support baseline is Native ESM. This plugin provides support for legacy browsers that do not support native ESM.
By default, this plugin will:
-
Generate a corresponding legacy chunk for every chunk in the final bundle, transformed with @babel/preset-env and emitted as SystemJS modules (code splitting is still supported!).
-
Generate a polyfill chunk including SystemJS runtime, and any necessary polyfills determined by specified browser targets and actual usage in the bundle.
-
Inject <script nomodule>
tags into generated HTML to conditionally load the polyfills and legacy bundle only in browsers without native ESM support.
-
Inject the import.meta.env.LEGACY
env variable, which will only be true
in the legacy production build, and false
in all other cases.
Usage
import legacy from '@vitejs/plugin-legacy'
export default {
plugins: [
legacy({
targets: ['defaults', 'not IE 11']
})
]
}
Options
targets
polyfills
-
Type: boolean | string[]
-
Default: true
By default, a polyfills chunk is generated based on the target browser ranges and actual usage in the final bundle (detected via @babel/preset-env
's useBuiltIns: 'usage'
).
Set to a list of strings to explicitly control which polyfills to include. See Polyfill Specifiers for details.
Set to false
to avoid generating polyfills and handle it yourself (will still generate legacy chunks with syntax transformations).
additionalLegacyPolyfills
-
Type: string[]
Add custom imports to the legacy polyfills chunk. Since the usage-based polyfill detection only covers ES language features, it may be necessary to manually specify additional DOM API polyfills using this option.
Note: if additional plyfills are needed for both the modern and legacy chunks, they can simply be imported in the application source code.
ignoreBrowserslistConfig
modernPolyfills
-
Type: boolean | string[]
-
Default: false
Defaults to false
. Enabling this option will generate a separate polyfills chunk for the modern build (targeting browsers with native ESM support).
Set to a list of strings to explicitly control which polyfills to include. See Polyfill Specifiers for details.
Note it is not recommended to use the true
value (which uses auto-detection) because core-js@3
is very aggressive in polyfill inclusions due to all the bleeding edge features it supports. Even when targeting native ESM support, it injects 15kb of polyfills!
If you don't have hard reliance on bleeding edge runtime features, it is not that hard to avoid having to use polyfills in the modern build altogether. Alternatively, consider using an on-demand service like Polyfill.io to only inject necessary polyfills based on actual browser user-agents (most modern browsers will need nothing!).
renderLegacyChunks
-
Type: boolean
-
Default: true
Set to false
to disable legacy chunks. This is only useful if you are using modernPolyfills
, which essentially allows you to use this plugin for injecting polyfills to the modern build only:
import legacy from '@vitejs/plugin-legacy'
export default {
plugins: [
legacy({
modernPolyfills: [
],
renderLegacyChunks: false
})
]
}
Polyfill Specifiers
Polyfill specifier strings for polyfills
and modernPolyfills
can be either of the following:
Example
import legacy from '@vitejs/plugin-legacy'
export default {
plugins: [
legacy({
polyfills: ['es.promise.finally', 'es/map', 'es/set'],
modernPolyfills: ['es.promise.finally']
})
]
}
Content Security Policy
The legacy plugin requires inline scripts for Safari 10.1 nomodule
fix and SystemJS initialization. If you have a strict CSP policy requirement, you will need to add the corresponding hashes to your script-src
list:
MS6/3FCg4WjP9gwgaBGwLpRCY6fZBgwmhVCdrPrNf3E=
tQjf8gvb2ROOMapIxFvFAYBeUJ0v1HCbOcSmDNXGtDo=
These values can also be retrived via
const { cspHashes } = require('@vitejs/plugin-legacy')
References