RFC: New Next.js Polyfill Behavior #36601

SukkaW · 2022-05-01T11:23:38Z

SukkaW
May 1, 2022

Background

Next.js has next-polyfill-nomodule and next-polyfill-module. The implementation detail of the module can be found here:

Next.js uses <script nomodule> to load next-polyfill-nomodule on unsupported browsers only, and bundles next-polyfill-module in the main bundle (along with Next.js client-side code).

In RFC #33227 (Implemented by #36584), Next.js is starting experiments dropping legacy browsers support.

Pitfalls

The current approach greatly reduces the bundle size when first introduced back in Next.js 9.x. However, it has some problems:

Next.js will always include the polyfill for String.prototype.trimStart, String.prototype.trimEnd, Array.prototype.flat, and Promise.prototype.finally in the main bundle (because they are all parts of next-polyfill-module), even if a website doesn't use any of those features, or doesn't target legacy browsers.
Next.js doesn't include polyfills for Math functions (IE11 polyfills: missing Math.trunc #11714, Polyfill Math globals #14716), and developers have to manually include and ship the polyfill in the main bundle even for browsers that support it.
Next.js doesn't include every polyfill required for full ES2019 compatibility (It lacks the polyfill for Object.fromEntries). See issues Edge 18 (Object.fromEntries) not supported even with correct polyfills #16715, Rule no-unwanted-polyfillio wrongly reports error on es2019 rule #33072, Update polyfill for eslint no-unwanted-polyfillio rule #33170, and Add Object#fromEntries polyfill (with 6 lines of code) #36426.
With the ECMAScript Spec rolling out new features every year, the size of the next-polyfill-module will continuously increase. ES2020 introduces BigInt, String.prototype.matchAll, and Promise.allSettled, ES2021 introduces String.prototype.replaceAll, Promise.any, and WeakRef. And in June of this year, ES2022 will introduce String.prototype.at, Array.prototype.at, TypedArray.prototype.at, and Object.hasOwn. The bundle size will become huge even if we only include part of those features' polyfill into next-module-polyfill. And once again, not everyone is using all of the new ES features or targets old browsers.
core-js not only provides polyfills for features not supported on legacy browsers but also corrects the behavior for those browsers that implement features incorrectly. For example, core-js provides a workaround for a critical bug about Array.prototype.reduce introduced in Chrome 80-82, a workaround for a critical bug about Array.prototype.reverse introduced in Safari 12, a workaround for a wrong implementation of Reflect.set on Edge 18. Since Next.js doesn't use core-js (it maintains a next-polyfill-module), although the bundle size is reduced, the critical bug fixes from core-js is also omitted.

Possible Solutions

The proposal is trying to accomplish these goals:

Next.js should only load required polyfills on legacy browsers.
Next.js shouldn't include any polyfill for features that sites do not use at all.
Next.js should include critical bug fixes from core-js.
Next.js should allow sites to experiment latest shipped proposals (E.g. Object.hasOwn is already in ECMAScript stage 4, is shipped in Firefox, Chrome, and Safari 15.4 at the time being, and will be landed in ES2022)

Here I propose two solutions:

Solution 1

Deprecates next-polyfill-nomodule.

If browserlist targets browsers without <script nomodule>, Next.js should create two different sets of bundles, one set targets legacy browsers that doesn't have <script nomodule> support, and another set targets modern browsers with <script module> support. The final emitted HTML will be like this:

<head>
  <!-- old ECMAScript syntax and polyfills for legacy browsers. This will only load on legacy browsers and Safari 10.1 -->
  <script nomodule defer src="main.[hash1].js"></script>
  <!-- modern ECMAScript syntax and polyfills only for modern browsers. This will only load on modern browsers and Safari 10.1 -->
  <script module src="main.[hash2].js"></script>
</head>

If browserlist only targets modern browser, Next.js should only create one bundle. The final emitted HTML will be like this:

<head>
  <!-- modern ECMAScript syntax and polyfills only for modern browsers. This will only load on modern browsers and Safari 10.1 -->
  <script module src="main.[hash3].js"></script>
</head>

The approach is used by Parcel bundler, and Vue CLI (when creating a new Vue app).

Pros:

We can fully utilize SWC's env.mode (Babel's useBuiltins).
With mode set to usage, SWC / Babel will only include required polyfills.

Cons:

~~According to the SWC's documentation:~~
~~> The usage mode is currently not as efficient as Babel, yet.~~
It will emit two different sets of bundles, which means double the compilation time and double the disk space occupied.
It may reduce the cache ratio of the CDN.
Safari 10.1 supports <script module> but doesn't support <script nomodule>, which means Safari 10.1 will download and executed all of the codes.
If a site defines a browserlist that targets legacy browsers, we will have to manually parse and split it into two ranges, one legacy range (for <script nomodule>) and one modern range (for <script module>).

Solution 2

We will keep next-polyfill-nomodule to include polyfills targeting legacy browsers without <script nomodule> supports.
We will let SWC / Babel transforms the modern JavaScript syntax to support browsers defined in browserlists.
We will let SWC / Babel only include polyfills from core-js to target the modern browsers that support <script nomodule>.

The final HTML output will be like this:

<head>
  <!-- old ECMAScript syntax, polyfills for legacy browsers only. This will only load on legacy browsers and Safari 10.1 -->
  <script nomodule defer src="polyfill.[hash1].js"></script>
  <!-- old ECMAScript syntax, polyfills for modern browsers only. This will load on all browsers -->
  <script src="main.[hash2].js"></script>
</head>

Pros

Next.js only needs to create one set of a bundle and a separate polyfill bundle from next-polyfill-nomodule.

Cons

~~According to the SWC's documentation:~~
~~> The usage mode is currently not as efficient as Babel, yet.~~
Currently, it is impossible for SWC or Babel to both transforms modern ECMAScript syntax to legacy compatible syntax while including polyfills from core-js to target only modern browsers.
If a site defines a browserlist that targets legacy browsers, we will have to manually parse and split it into two ranges, one legacy range (when transforming syntax) and one modern range (to include polyfills for modern browsers).

cc @kdy1 @styfle @timneutkens @developit

Austaras · 2022-05-01T12:33:15Z

Austaras
May 1, 2022

I personally prefer solution 1 which is employed by parcel, @vue/cli and @angular/cli. It would be nice if next could bring this ability to react world.

1 reply

SukkaW May 1, 2022
Author

And which one of two solutions do you prefer then?

SukkaW · 2022-05-11T07:16:32Z

SukkaW
May 11, 2022
Author

Update

Mention IE11 polyfills: missing Math.trunc #11714 and Polyfill Math globals #14716 in the RFC.

Update

swc has improved the usage option: swc-project/swc@dd0a152

0 replies

Jessidhia · 2022-08-01T04:42:11Z

Jessidhia
Aug 1, 2022

useBuiltIns: 'usage' is by far my favorite feature of @babel/preset-env and what truly separates it from its predecessors. It would be great to be able to use its equivalent in the next / swc world.

I am definitely in favor of Solution 1; Solution 2 requires the script[module] bundle to also include unnecessary syntax transforms that bloat code size, makes debugging production issues harder and dodges potential browser optimizations.

Some points:

The usage mode is currently not as efficient as Babel, yet.

I don't think this is too major of a concern, as long as it's sure to never underpolyfill. Personally I think that even a naive usage implementation is better than how error-prone manual polyfilling is.

If using usage polyfills, a webpack loader pass must also run on code from node_modules (with core-js and other known niche (or not) polyfills excluded; this list would need to be user-augmentable). Failing to do that can lead to required polyfills being missed and possible runtime crashes on non-current browsers.

In Solution 1, if some method of diffing the polyfill list of the module and nomodule builds is devised, the polyfills unique to the nomodule build could be split off into a separate entry point and injected as a second <script nomodule> tag before the user's <script nomodule> entry point; this could improve the CDN cache ratio similar to Solution 2 as the nomodule polyfills are unlikely to ever change without browserslist changes. This effectively would deprecate next-polyfills-nomodule and replace it with a codegen equivalent.

There is also a way to potentially reduce the build time penalty of Solution 1, but similar to Solution 2, it would depend on a feature that does not currently exist: a way to tell the preset-env equivalent to limit the "input level" of its code.

Think of it as something similar to tsconfig.json's lib option; if you only specify, say, es2018, then globals/methods from es2019+ are not defined. The equivalent would need to, say, enable only transforms between es2018 and the baseline of script[module] browsers, even if the compiler supports es2022 syntax and transforms. This would allow us to separate compilation into two passes: one to downlevel code down to the script[module] + script[nomodule] baseline, and one to downlevel that code to the lowest supported browsers; this would produce output similar to Solution 1, but with potentially shorter build times by not doing the same code transforms twice.

Similarly to Solution 1, projects targeting only modern-enough browsers would not pay for this second pass; also similarly to Solution 1, only the nomodule bundle would need to pay for the additional transforms required. This can also make the nomodule polyfill separation easier, perhaps even using entry mode for codegen purposes.

This does have greater complexity with its own caveats:

This requires two compiler passes and assumes that compiler passes are neatly separable. This is similar to the assumption at the time of babel's yearly presets (e.g. using es2017 alone to produce es2016 code, or es2017 + es2016 to produce es2015 code), but babel did not necessarily run transforms in "reverse year order", there is an internal reorder in the config reader, one that would not be possible when doing two compiler passes.
The potential improved build times assumes that this cheaper second pass with fewer transforms is in fact cheaper than just doing a second full build like in Solution 1.
- If swc guarantees that all transforms are idempotent, the ability to specify input code source level may not even be required, but that would make the second parse step more expensive.

5 replies

SukkaW Aug 1, 2022
Author

I don't think this is too major of a concern, as long as it's sure to never _under_polyfill. Personally I think that even a naive usage implementation is better than how error-prone manual polyfilling is.

Actually, swc does both under-polyfill and over-polyfill. And currently the swc team and contributors are too busy to have time working on the issue.

Austaras Aug 1, 2022

I don't think this is too major of a concern, as long as it's sure to never _under_polyfill. Personally I think that even a naive usage implementation is better than how error-prone manual polyfilling is.

Actually, swc does both under-polyfill and over-polyfill. And currently the swc team and contributors are too busy to have time working on the issue.

No it has recently been fixed and released in 1.2.220

SukkaW Aug 1, 2022
Author

I personally prefer Solution 1 as well. It serves smaller bundles for the modern client. And swc is fast enough to compile two sets of bundles while still being faster than babel.

Solution 2 is closer to the current Next.js behavior and easier to adopt.

fireairforce Aug 25, 2022

I don't think this is too major of a concern, as long as it's sure to never _under_polyfill. Personally I think that even a naive usage implementation is better than how error-prone manual polyfilling is.

Actually, swc does both under-polyfill and over-polyfill. And currently the swc team and contributors are too busy to have time working on the issue.

No it has recently been fixed and released in 1.2.220

Can u please give a release-note here, i can't find the changelog on the swc CHANGELOG document: https://github.com/swc-project/swc/blob/main/CHANGELOG.md#12220---2022-07-28

SukkaW Aug 25, 2022
Author

@fireairforce It is the swc commit (swc-project/swc@dd0a152) that solves this issue.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: New Next.js Polyfill Behavior #36601

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 3 comments 6 replies

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

RFC: New Next.js Polyfill Behavior #36601

SukkaW May 1, 2022

Background

Pitfalls

Possible Solutions

Solution 1

Pros:

Cons:

Solution 2

Pros

Cons

Replies: 3 comments · 6 replies

Austaras May 1, 2022

SukkaW May 1, 2022 Author

SukkaW May 11, 2022 Author

Jessidhia Aug 1, 2022

SukkaW Aug 1, 2022 Author

Austaras Aug 1, 2022

SukkaW Aug 1, 2022 Author

fireairforce Aug 25, 2022

SukkaW Aug 25, 2022 Author

SukkaW
May 1, 2022

Replies: 3 comments 6 replies

Austaras
May 1, 2022

SukkaW May 1, 2022
Author

SukkaW
May 11, 2022
Author

Jessidhia
Aug 1, 2022

SukkaW Aug 1, 2022
Author

SukkaW Aug 1, 2022
Author

SukkaW Aug 25, 2022
Author