Update Polyfill Docs / Examples

[jonkwheeler]

Bug report

The polyfill docs are out of date

My most recent stack update I included a new dependency called simplebar-react (simplebar). While the component works great, the rest of the site stopped working correctly (literally all the other pages). I knew it was something global. No error messages indicating anything wrong either. A truly nasty bug.

After removing simplebar-react, I noticed the rest of the site began to work again. Exploring their docs, I noticed there are issues with it bundling in Gatsby due to it's polyfills, so I got curious. Turns out I've been polyfilling incorrectly with Next.js for awhile now (though I was using the once "suggested" way in the Next.js examples). Once I tried the newly suggested way, the App began to work again.

Proposal

• Detect if someone is loading polyfills the "not suggested" way, and warn them to change this. The old way is shown here: https://github.com/vercel/next.js/blob/canary/examples/with-polyfills/next.config.js. I noticed the example now says

❗️ Warning: This example is not the suggested way to add polyfills and is known to cause issues with bundling. See the browser support docs for the correct way to load polyfills.

The way in which I was polyfilling worked (until now), any yes I indeed ran into bundling issues.

module.exports = {
  webpack: function (cfg) {
    const originalEntry = cfg.entry
    cfg.entry = async () => {
      const entries = await originalEntry()

      if (
        entries['main.js'] &&
        !entries['main.js'].includes('./client/polyfills.js')
      ) {
        entries['main.js'].unshift('./client/polyfills.js')
      }

      return entries
    }

    return cfg
  },
}

• Once I ran this screenshot by @timneutkens

he said ~~yes, that's correct. Meaning, import them on _app.tsx. However, he went on to say "all of those imports are included in Next.js already and only loaded for older browsers that need them". This is news to me. This change happened in the past year, but I setup my polyfills over a year ago, and I guess never got the memo.

I think this link https://github.com/vercel/next.js/blob/canary/packages/next-polyfill-nomodule/src/index.js needs to be added to the docs somewhere to show what's automatically poyfilled and what isn't. Tim made comment that "this section needs work", and asked I create this ticket (so don't burn me). https://nextjs.org/docs/basic-features/supported-browsers-features#polyfills

The Gist

Update the polyfill example, and add a detailed explanation of why you polyfill this way (due to bundling issues). A likely relevant polyfill would be the 'intersection-observer' for IE11. Perhaps the example could include that.

[balazsorban44]

Hi, we now have an ESLint rule for that https://nextjs.org/docs/messages/no-unwanted-polyfillio

[balazsorban44]

This issue has been automatically locked due to no recent activity. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.