Document the extent of ES6 polyfilling

[jhorneman]

Assuming no major misunderstandings from my side: It was not clear me from the documentation that create-react-app installs fetch (whatwg-fetch), and that this is then available to me in my own JavaScript code. I only found this out when I looked at create-react-app (CRA)'s package.json file and tried it out.

I assume the presence of fetch and its use in user code is intended, but I cannot assume this is true for everything inside CRA's package.json file.

It seems to me there are three kinds of dependencies inside create-react-app:

1. development dependencies, such as rimraf, which are needed for CRA's core functionality but not for any code running in the browser - the equivalent of installing with --save-development.
2. dependencies that are implementation details and while they might be useful for my own code, are not guaranteed to stay in future versions of CRA.
3. dependencies that I can use in my own code and that are guaranteed to stay, such as, presumably, fetch, until fetch is available natively in all major browsers.

It is hard to tell right now which dependency is which. It would be great to have this documented somewhere. I would propose something, but I lack the requisite knowledge.

[thien-do]

Hi @jhorneman , let's keep track here #531

[jhorneman]

Thanks. Sorry, I only looked through the docs issues, not the pull requests. I'll do that next time!

[gaearon]

It's not meant to be used as a dependency, it's a polyfill. So you should not try to import it.

It just makes sure you have a global fetch() and global Promise whether or not browser implements them.

Wrong:

import fetch from 'whatwg-fetch'
fetch()

Right:

fetch()

I agree we should document available polyfills.

[gaearon]

People commonly mistakingly assume Create React App polyfills ES6 runtime methods like Array.from. We should document this.

[stujo]

What is the best practice to adding polyfills to CRA apps?

For example: I want to polyfill Array.includes and I'm wondering where and how to add it and be consistent with the CRA worldview

[gaearon]

If you're okay with using CDNs, consider using https://polyfill.io/. Don't forget to add Promise, fetch and Object.assign to excludes because they're already bundled with CRA.

If you'd prefer to bundle them with your app, you can install core-js and import corresponding polyfills from src/index.js before other imports. I don't recommend importing complete core-js because it is pretty heavy.

[stujo]

Ahh

Ahh thanks Dan, at the time instead of src/index.js I had added it to the end of config/polyfills.js :

if (!Array.includes) {
  require('core-js/fn/array/includes');
}

[sheerun]

@gaearon Should babel-preset-env take care of polyfilling only needed built-ins?

[sheerun]

ping @hzoo