Skip to content

Commit

Permalink
[docs] Clarify polyfill support (#39272)
Browse files Browse the repository at this point in the history
Currently next.js polyfills a [subset](https://github.com/vercel/next.js/blob/canary/packages/next-polyfill-nomodule/src/index.js) of APIs for `nomodule` browsers (such as IE 11), however it's not immediately clear to developers which APIs are transparently polyfilled.

For example, currently `Object.entries` is polyfilled and thus is usable in IE 11, but [it was decided](#15772 (comment)) that `Object.fromEntries` should not be polyfilled. As a developer, this is a confusing situation until you end up finding the `next-polyfill-nomodule` list of polyfills that are included.

This PR attempts to improve the Supported Browser Features page by:
- linking to the list of polyfills
- clarifying that custom polyfills are required for IE11 (and other old browser) compatibility
- moving the section on Sever-Side polyfills further down the page so all browser polyfill sections are better grouped together

## Documentation / Examples

- [x] Make sure the linting passes by running `pnpm lint`
- [x] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
  • Loading branch information
josh- committed Aug 3, 2022
1 parent 4d0783d commit a189542
Showing 1 changed file with 6 additions and 6 deletions.
12 changes: 6 additions & 6 deletions docs/basic-features/supported-browsers-features.md
Expand Up @@ -8,7 +8,7 @@ Next.js supports **IE11 and all modern browsers** (Edge, Firefox, Chrome, Safari

## Polyfills

We transparently inject polyfills required for IE11 compatibility. In addition, we also inject widely used polyfills, including:
We inject [widely used polyfills](https://github.com/vercel/next.js/blob/canary/packages/next-polyfill-nomodule/src/index.js), including:

- [**fetch()**](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) — Replacing: `whatwg-fetch` and `unfetch`.
- [**URL**](https://developer.mozilla.org/en-US/docs/Web/API/URL) — Replacing: the [`url` package (Node.js API)](https://nodejs.org/api/url.html).
Expand All @@ -18,13 +18,9 @@ If any of your dependencies includes these polyfills, they’ll be eliminated au

In addition, to reduce bundle size, Next.js will only load these polyfills for browsers that require them. The majority of the web traffic globally will not download these polyfills.

### Server-Side Polyfills

In addition to `fetch()` on the client-side, Next.js polyfills `fetch()` in the Node.js environment. You can use `fetch()` in your server code (such as `getStaticProps`/`getServerSideProps`) without using polyfills such as `isomorphic-unfetch` or `node-fetch`.

### Custom Polyfills

If your own code or any external npm dependencies require features not supported by your target browsers, you need to add polyfills yourself.
If your own code or any external npm dependencies require features not supported by your target browsers (such as IE 11), you need to add polyfills yourself.

In this case, you should add a top-level import for the **specific polyfill** you need in your [Custom `<App>`](/docs/advanced-features/custom-app.md) or the individual component.

Expand All @@ -40,6 +36,10 @@ Next.js allows you to use the latest JavaScript features out of the box. In addi
- [Class Fields](https://github.com/tc39/proposal-class-fields) and [Static Properties](https://github.com/tc39/proposal-static-class-features) (part of stage 3 proposal)
- and more!

### Server-Side Polyfills

In addition to `fetch()` on the client-side, Next.js polyfills `fetch()` in the Node.js environment. You can use `fetch()` in your server code (such as `getStaticProps`/`getServerSideProps`) without using polyfills such as `isomorphic-unfetch` or `node-fetch`.

### TypeScript Features

Next.js has built-in TypeScript support. [Learn more here](/docs/basic-features/typescript.md).
Expand Down

0 comments on commit a189542

Please sign in to comment.