RFC: Change default JS/CSS output to target modern browsers

[styfle]

Edit: This shipped in Next.js 13! Learn more: https://nextjs.org/blog/next-13

---

Background

Next.js currently targets ES5 for JS output and autoprefixes CSS in order to support legacy browsers. This results in much larger JS and CSS output because newer features need to be down-leveled.

For example, ES5 doesn’t include many of the JavaScript syntax features we use today such as async/await, Object rest/spread, for-of loop, optional chaining, nullish coalescing, etc.

In addition to syntax down-leveling, Next.js also injects polyfills such as Object.assign(), URL, etc. However, those are only included in browsers that require them (using the nomodule attribute).

Proposal

We propose changing the default Next.js output to target modern browsers that support ES Modules, which accounts for 93% of global usage:

• Edge 16+
• Firefox 60+
• Chrome 61+
• Safari 11+
• Opera 48+

This change would reduce JS/CSS bundle size for all applications that use the default Next.js configuration. Next.js will continue to autoprefix CSS for the supported browsers above when necessary.

Changing the default output target would align Next.js with Vite and SvelteKit. In addition, most other tools don’t support ES5 such as esbuild and Angular.

The notable browser missing here is Internet Explorer which will soon reach End Of Life.

This would also fix obscure bugs caused by down-leveling to ES5 such as #30892.

Note: This proposal is not suggesting changing the output to ESM, but rather using that feature as a way to determine which browsers we consider “modern”.

Backwards Compatibility

Changing default configuration is considered semver major and will not ship until Next.js 13.

However, Next.js will still maintain backwards compatibility for developers who wish to upgrade to Next.js 13 and continue supporting legacy browsers, such as IE 11. There are a few options:

1. Opt-out flag: Developers can provide legacyBrowsers: true in next.config.js to emit the same JS/CSS output as today. This could work exactly the same as today. Alternatively, it could create two builds: one modern <script type=module> and one legacy <script nomodule> , therefore increasing build times.
2. Browserlist support: Add built-in support for browserslist. We already load .browserslistrc and browserslist from package.json for PostCSS, but don’t pass it to the JavaScript transformations (yet). Browserslist is already supported in SWC, so we’d only have to pass the browserslist loading result as an option. (related discussion)

Release Timeline

Changing default configuration is considered semver major and will not ship until Next.js 13.

However, users may wish to adopt this change today, so we could provide a flag to enable the new behavior with Next.js 12. Similar to the options above but reversed:

1. Opt-in flag legacyBrowsers: false in next.config.js
2. Modify .browserslistrc or browserslist in package.json

Feedback

We’d love to hear your feedback on which solution would work better for your team and why.

[kachkaev]

Note: This proposal is not suggesting changing the output to ESM, but rather using that feature as a way to determine which browsers we consider “modern”.

Does this mean that some *.js files in .next will remain using CommonJS? Asking because of this issue:

• Issue with backend-side ES6 imports with "type":"module" with an express/nextjs setup #24334

I have a project with a bunch of ESM scripts, for which I added "type": "module" in package.json. This broke Next.js commands, so I had to add another package.json into .next dir as a workaround.

If Next outputs are for modern browsers, it’d be really cool if it was ESM everywhere! Altenratively, if files in .next have explicit .cjs and .mjs extensions, an app should work regardless of "type": "module" in package.json.

[styfle]

Correct, this RFC does not address ESM vs CJS but it can be addressed in a follow up RFC, thanks!

[developit]

Will Next's output apply workarounds for Edge and Safari? I believe Safari 11 on iOS still crashes when encountering async arrow functions within a class body, and Edge 16 is missing support for non-shorthand destructured argument defaults in Arrow Functions, etc (full list).

[styfle]

I made a demo and tested Safari 11 on macOS and iOS and both work.

• Safari 11 macOS

• Safari 11 iOS

I also tried Edge 16 and it works too.

• Edge 16 Windows

[developit]

Is this demo using the features that don't work in those browsers though? There's a list in the babel-preset-modules repo.

[timneutkens]

@developit thanks for the reminder. We'll include the preset-modules transforms 🙏

[kasperaamodt]

When will the Opt-in flag be available for people who want to test, and adopt it early?

[kylemh]

Similarly, will there be an issue I can watch for this? I'd like to adopt ASAP.

[kylemh]

It appears as though this is available! #37142 (comment)

but also warning: https://twitter.com/styfle/status/1529823517260120066?s=20&t=ZJeN4j3VqRCUtOMECjwVzg

[eric-burel]

1. I'd advocate for 2 bundles if the legacy build is enabled, Meteor-style, the use case being support for older browsers while not affecting modern browser with a less optimized build.

What is a modern browser is something that will evolve with time, so this pattern is probably here to stay. For many companies and products supporting legacy browsers will always be important, yet they don't want to reduce the quality of the main build.

The build time is really not a problem here imo, if you want a legacy browsers you have good business reason for it and you'd accept a small overhead when releasing your app in prod.
You can opt-out of the legacy build during dev, test or local build anyway.

2. About browserlist, one thing I don't like is that you cannot really build it based on your app dependencies. You'd probably want this option as well though, so you can control the build better. However, what happens if I want to include non-modern browser to the list? You still end up with the need to produce 2 bundles.

[Brooooooklyn]

For reference https://www.tiktok.com now transforms all code to ES2015 and does not support any browsers that do not support Promise natively

[ryanoglesby08]

I'd like to kindly remind folks as we work towards a solution here that while the majority of individuals are using modern browsers, the market for Internet Explorer 11 (and below) is still large even though it is reaching end of life soon. For example, the company I work for gets about 20% of annual revenue through IE 11. This is primarily through B2B integrations with older SAP instances. Many IT departments are very slow to upgrade, which puts our end customers in a position where they do not have a choice of what browser to use, so asking the end customer to upgrade to a modern browser is sometimes not possible. We have more users on IE 11 than on modern Firefox or Safari.

We recently made the decision to use Next.js, partially due to its built in support for IE 11, so I ask that we keep this large customer base in mind.

---

That being said, is there an option to have 2 builds, modern and legacy, and then do user agent sniffing on the server to serve the appropriate bundle? It would be nice to relegate the ES5 transpiling and polyfilling to the legacy browser bundle only. The tradeoff of a longer build time is fine if I'm giving my customers a better experience by serving a leaner bundle to modern browsers.

I'm curious if Next.js could also handle modern and legacy CSS stylesheet bundles? AFAIK Differential Serving using module/nomodule is specific to <script> tags. Can we build a modern and legacy CSS bundle also and serve it to the appropriate browser?

[hu0p]

I like the idea of adding opt-in support and configuration for v12 using built-in browserlist support in package.json. It seems to require the least amount of effort. It also feels better in terms of feature alignment since if I follow correctly there's currently no way to accomplish this with SWC. As far as I can tell, if someone would like to do this in a project today, it would only be possible if they fall back to using Babel which has other obvious performance drawbacks and is (relatively) more painful to configure.

Adding support in this way cleanly tees up the wider rollout for this feature to be as simple as a configuration flip. I don't know when v13 is supposed to be released, but this way if enough users express a desire to push this change back (for example until after IEs EoL) their concerns can be addressed appropriately without preventing other users from experiencing the benefits of a lighter bundle with the fastest compiler today.

[danieleloscozzese]

I’m sympathetic to the continued need to support IE but I don’t think that it should be so influential as to bend the implementation for the vast majority of end-users of Next.is apps.
That said I myself would prefer a solution incorporating browserslist in order to give the support to the “standard” (for want of a better word) tooling to this end. I think a decent default is fine, but I’m not sure that a toggle is necessarily of great value if browserslist is supported: and I do really think it should be. Being able to switch between two defaults with a flag could be handy, but I don’t think it’s enough to then not support browserslist.

[matamatanot]

hook_optimizers will no longer be necessary.

https://github.com/vercel/next.js/blob/canary/packages/next-swc/crates/core/src/hook_optimizer.rs
https://github.com/vercel/next.js/blob/canary/packages/next/build/babel/plugins/optimize-hook-destructuring.ts

[developit]

That optimization is specifically for Chrome, dropping IE support wouldn't affect it.

[tommhuth]

So I'm trying to get Next 12.1.6 to ignore older browsers like IE11, and I've added a .babelrc with targets and a .browserslistrc. When building they seem to be used like expected, but when I inspect the source code used, it is still ES5, with all vars and no arrow functions.

Am I forced to use ES5? Some other comments and the documentation seem to indicate that that is not the case. I understand that some people need to support older browsers still, but why force that on everybody?

[jaworek]

I found this discussion some time ago. It does not seem that Next currently respects .browserlists config at the moment.

#12826

[timneutkens]

I've implemented the JS part of this RFC and the experimental flags to try it out are landed in 12.2:
https://nextjs.org/blog/next-12-2

We've added experimental support for shipping only modern JavaScript by modifying browsersList. You can opt-into this behavior by setting browsersListForSwc: true and legacyBrowsers: false in the experimental option of next.config.js.

• browsersListForSwc: true enables browserslist support for JS
• legacyBrowsers: false enables the future default that targets the browsers mentioned in the RFC. This flag depends on browsersListForSwc so in order to try it out you'll want to use this config:

experimental: {
   browsersListForSwc: true,
   legacyBrowsers: false
}

[markerikson]

FWIW I just tried out setting browsersListForSwc in replayio/devtools#7291 , along with a custom browserslist value to match what we previously were doing with @babel/preset-env. I confirmed that with SWC instead of Babel and default SWC behavior in Next 12.1, our bundle sizes went up by about 40K, and with SWC + Next 12.2 + the custom browserslist behavior those same bundle sizes went down by about 8K. So, this appears to be working as desired!

[thilak-rao]

The build fails when I use a browserslist config that extends a sharable browserslist config which includes /browserslist-stats.json in it.

I'm on next 12.2.1 and next.config.js includes:

experimental: {
    browsersListForSwc: true,
    legacyBrowsers: false,
  }

[Jessidhia]

The use of browserslist for transforms also brings to mind the use of browserslist for polyfilling (swc's mode option, babel/preset-env's useBuiltIns option). There is a "third party RFC" with more details on this point: #36601

[christiankaindl]

I am still using babel, because I use vanilla-extract. Setting legacyBrowsers: false doesn't do anything for me, even when used together with browsersListForSwc: true (yes, I am not using SWC, but still tried it). Does the legacyBrowsers: false config only work for SWC?

In the meantime I manually added the new defaults via browserslist in package.json from here:

next.js/packages/next/shared/lib/constants.ts

Line 29 in 81850eb

export const MODERN_BROWSERSLIST_TARGET = [

So in package.json:

{
  "browserslist": [
    "chrome 61",
    "edge 16",
    "firefox 60",
    "opera 48",
    "safari 11"
  ]
}

[zgreen]

FWIW, I've been using vanilla-extract in Next.js with SWC (not Babel) for a while now, and it works well. YMMV, but the babel plugin is not required.

Having said that, I'm also curious to know whether or not setting legacyBrowsers: false works only for SWC.

[christiankaindl]

Oh I didn't know that, thanks for letting me know!

[styfle]

This shipped in Next.js 13!

Learn more: https://nextjs.org/blog/next-13