Vite + @vitejs/plugin‑legacy: Balancing Legacy Target and Polyfills for Zero‑Downtime Migration

Vite + @vitejs/plugin‑legacy: Target Decision for Zero‑Downtime Migration

Migrating a lightweight application to Vite while preserving uninterrupted service requires careful handling of the legacy bundle. The @vitejs/plugin‑legacy module produces a separate ES5‑compatible script that is loaded via a <script nomodule> tag, allowing modern browsers to consume the module‑based bundle.

The core of the decision rests on the legacy.target option. A broader target such as es2015 reduces polyfill imports and bundle size, but may break in older engines. Narrowing to es5 injects many polyfills, increasing size but maximizing compatibility.

Additionally, the noExternal flag can exclude large dependencies from the legacy build, lowering duplication but risking runtime errors if the library is unavailable in the legacy context. The plugin also respects the project’s browserslist; an absent or misconfigured entry can lead to inconsistent polyfill sets between releases.

Because Vite’s defaults and the plugin’s polyfill logic evolve, the exact trade‑off between bundle size, build time, and browser coverage is not fixed. Determining the appropriate configuration requires balancing these factors against the target audience’s browser profile.

Open Questions

• What is the optimal legacy.target value to achieve acceptable bundle size while maintaining support for IE11 in a small app?
• How does the noExternal setting affect polyfill injection and duplication across the legacy bundle?
• Should the project’s browserslist be explicitly defined or rely on Vite defaults to ensure consistent polyfill coverage?