Feature request: better polyfill experience for modern targets

[nulladdict]

Description

Currently there are two main ways of adding polyfills to modern builds. Using an external polyfill service or using plugin-legacy with modern options. In this issues I want to focus on the plugin-legacy experience

If users want to only add polyfills to modern build they need to do one of:

• Declare them upfront using modernPolyfills: string[] which feels somewhat pointless because they can just import the modules directly in the main entrypoint instead and skip the plugin altogether
• Use auto-detection with modernPolyfills: true, modernTargets: string | string[] which will auto-detect used features and inject polyfills

Auto detection relies on babel (through babel-plugin-polyfill-corejs3 and babel-plugin-polyfill-regenerator) which leads to a couple of consequences

First, plugin needs to transform all chunks using babel. babel is slower than swc but since it transforms built chunks (as far as I understand) it shouldn't be a big issue

Second, the syntax for targets in esbuild and babel is very different. esbuild (and vite) currently do not support browserslist while babel does. This leads to a bit of a confusion

esbuild and browserslist are not entirely compatible. There's browserslist-to-esbuild library that can convert from browserslists targets to esbuild. The conversion is lossy and discards anything that isn't supported by esbuild (e.g. samsung internet)

Before #20393 users had to set both build.target and modernTargets and were fully in control of what gets built with what target

After the PR users now have to unset build.target and set modernTargets which will transform browserslist query and set the esbuild target. This feels somewhat backwards (why does a plugin control the target and not the other way around?) and in rare cases can change the output (if the targets were sufficiently different)

Suggested solution

The ideal solution is for oxc, rolldown and then vite to support functionality that plugin-env provides. This way users can use oxc-based polyfill detection and entirely avoid plugin-legacy for modern build

As far as I could see, there's scaffolding for this in oxc but the functionality is not implemented yet and I have to idea if it's on the roadmap

Other solution is to teach plugin-legacy to use build.target as modernTargets which is more intuitive but requires syntax conversion. I'm not entirely sure it's possible since esbuild supports targets such as es2020 and browserslist doesn't. I'll investigate and post results in comments

Alternative

Do nothing and accept the current state. Maybe add a bit more clarity to plugin-legacy docs

Docs for modernTargets currently say:

• the option will override build.target
• if the option is not set it will fallback to the default value
• the option should not be set if the plugin renders legacy chunks

To me a couple of questions arise:

• if I don't set the option would build.target still be replaced by some default?
  • won't build.target fallback to its default value?
• if I want to both render legacy chunks and add modern polyfills what do I do?

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[brendanmatkin]

This comment got away from me haha - it kinda turned into a blog post, but I'll post anyway, it might be helpful.

Case Study

Here is a related problem that I just dealt with. For context, I need my app to be polyfilled for Chrome 49 and Safari 13.1.

Initially, I did not set modernTarget, but did set target and build.target to their respective equivalent syntaxes of Chrome 49 and Safari 13.1

• I got a polyfilled legacy bundle that worked as expected for Chrome 49, but Safari 13.1 was loading the modern bundle, and it was not polyfilled.
• Got warnings that build.target was being overridden by modernTarget, even though I didn't set it.
• There were legacy and modern bundles, but only legacy polyfills

It took me a minute to realize that if modern bundles are enabled (they are by default), then the boundary between the modern and legacy bundles is Native ESM + native ESM dynamic import + import.meta, no matter what the targets are set to. I also realized that the value of modernTarget is always applied to my app, including if it still has the default value, and regardless of the value build.target.

By default, modernPolyfills is false. In order to polyfill Safari 13.1, I need to polyfill my modern bundle by giving modernPolyfills an appropriate value. The legacy bundle will never load in Safari 13.1 if renderModernChunks is true, because Safari 12 is the earliest Safari to support native ESM, native ESM dynamic import, and import.meta. If I set modernPolyfills to true (not recommended), then Babel will use all the [default(?)] modernTarget browsers, compared to what features are detected in my code (plugin-legacy uses useBuiltIns: 'usage'), to get a bunch of polyfills that cover every edge case. I think most of the modern polyfills are redundant, which, I imagine, is why the devs recommend not doing that. For me, that was 58 polyfills for modern, compared to 81 polyfills for legacy. The easy way to see which polyfills are used is by running DEBUG=vite:legacy pnpm build with modernPolyfills: true.

For now, I still need to decide if I want to

• just leave in the extra polyfills. Most of them are not cutting edge features, and babel is using useBuiltIns: 'usage', so something in that default browser list wants these polyfills for my code
• check each polyfill in the modern bundle against caniuse, and manually include the appropriate polyfills (assuming it's detecting some edge cases that I will likely never see - e.g. Symbol: description in iOS 12.1).
• use cloudflare's polyfill service
• do a single legacy build for all browsers
• modify my code to not use the features that require polyfills

So there are definitely some fuzzy bits where the config experience could be improved, and/or the docs could be fleshed out a bit. @nulladdict -I bumped into annoying target syntax too, and also found the unsetting of build.target to feel backwards.

The ideal solution is for oxc, rolldown and then vite to support functionality that plugin-env provides. This way users can use oxc-based polyfill detection and entirely avoid plugin-legacy for modern build

Love this. Hopefully we get here. If we are very lucky, this will also work for legacy workers.

But, for now, I think my experience with this has some answers to @nulladdict 's lingering questions that might also be useful for others or for adding to the docs. Depending on what nulladdict finds in their investigation, I could do a PR to update docs later.

Missing Answers

if I don't set the option would build.target still be replaced by some default?

Yes. build.target is always replaced by modernTarget when using plugin-legacy, which currently has the default setting of 'edge>=79, firefox>=67, chrome>=64, safari>=12, chromeAndroid>=64, iOS>=12'. If you set modernTarget to something else, build.target will be replaced by that.

Additionally, I think build.cssTarget will also inherit those values for the modern bundle. For sure, it will always be set to 'chrome61' for the legacy bundle.

won't build.target fallback to its default value?

No. The plugin manually overrides build.target after the config is loaded (configResolved hook(s)), but before each build/bundle (generateBundle hook(s)).

UNLESS you are wondering if it will fallback to its default before another plugin runs after plugin legacy? In that case.. maybe? I'm not sure about that. But subsequent plugins will be running after the code is built and bundled, so I don't imagine many cases where that will matter, right? I don't really know.

if I want to both render legacy chunks and add modern polyfills what do I do?

Populate [modernPolyfills](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy#modernpolyfills) with core-js 3 specifiers, and/or [additionalModernPolyfills](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy#additionalmodernpolyfills) with paths to manually installed polyfills, or set to true.

Usually, you should not change the default modernTargets if you also want a legacy bundle. If you change any browsers in this list to a lower version than what they are now, nothing will change, because any lower version will load the legacy bundle anyway (nomodule etc). If you change it to anything higher, then there will be a gap of supported versions between the legacy bundle and whatever higher version you specify. That might be ok in your case, but would generally be undesireable.

e.g.

• your code uses Array.flatMap (Chrome 69+)
• default modernTarget is >=Chrome 64
• you change modernTarget to >=Chrome 107 (vite's new default build.target)

The bit of built code that uses flatMap works in browsers <=Chrome63, and >=Chrome69 (where nullish coalescing was introduced), but not any browser in between (i.e. Chrome 64-68).

I suppose if we wanted the modernTargets threshold to change, we would have to write a different detector. Currently it is

export const detectModernBrowserDetector: string = `import.meta.url;import("_").catch(()=>1);(async function*(){})().next()`

Other

There's browserslist-to-esbuild library that can convert from browserslists targets to esbuild.

plugin-legacy uses this internally, so I don't think it's a crazy suggestion. But going in the other direction seems trickier (esbuild target to browserslist), but converting to preset-env's targets object seems easyish.