Improve language around "npm run build fails to minify"

[franciscop]

I find this recommendation very harmful:

Open an issue on the dependency's issue tracker and ask that the package be published pre-compiled.

It seems I am not the only one:

[...] I don't want to set a precedence that Webpack can do whatever they want and force the Node.js ecosystem to change. Webpack is the one that is interacting badly and should be fixed, not every Node.js module using a supported feature. [...]

Please do open an issue on Webpack and let them know they're causing pain for both Webpack users and Node.js module maintainers.

• Sindre Sorhus

And with good reason, there are quite a few webpack issues in that package alone, and many more in Github at large.

What makes things worse is the tone of the section in the readme, which puts all of the blame on 3rd party authors. Let's read it commented (emphasized parenthesis mine):

Some third-party packages don't compile their code to ES5 before publishing to npm (why should they? It is not that common with Node, the initial target of NODE package manager). This often causes problems in the ecosystem because neither browsers (except for most modern versions) (not most, now things are quite different, specially for smaller companies/pages) nor some tools currently support all ES6 features. We recommend to publish code on npm as ES5 at least for a few more years (quite ambiguous and generic, normally it's recommended to support your actual users, not an arbitrary Javascript version).

To resolve this:

Open an issue on the dependency's issue tracker and ask that the package be published pre-compiled. (don't search for previous issues; adding more and more webpack-related issues to a library author is a good way to make friends).

Note: Create React App can consume both CommonJS and ES modules. For Node.js compatibility, it is recommended that the main entry point is CommonJS. However, they can optionally provide an ES module entry point with the module field in package.json. Note that even if a library provides an ES Modules version, it should still precompile other ES6 features to ES5 if it intends to support older browsers (I don't know who is using my libraries or what do they support).

Fork the package and publish a corrected version yourself. (and manually track future improvements and vulnerabilities)

If the dependency is small enough, copy it to your src/ folder and treat it as application code. (and manually track future improvements and vulnerabilities)

In the future, we might start automatically compiling incompatible third-party modules, but it is not currently supported. This approach would also slow down the production builds (without measuring this means nothing. 0.001% slower? 200% slower? Also, they will likely result in smaller files and faster runtime).

From a conceptual point of view, it also makes sense that library authors publish the lean, modern version of the library and then only those who want to support X or Y browser support it. Library authors should not be taking user support decisions on behalf of their users. Probably a big contributor of JS bundle size now is that libraries compile to ES5, and that will be very difficult to change even in few years (or now depending on your audience) when there is no need at all.

So my recommendation is to change that bit of the readme to something more agnostic:

---

npm run build fails to minify

create-react-app doesn't support modern javascript on 3rd party libraries yet. As support from browsers grows we will add support to compile the 3rd party code to make sure your actual users are supported. Builds will be very likely smaller and will run faster in the browser. Until then:

1. Fork the package and compile the code to the version that you want to support.

2. If the dependency is small enough, copy it to your src/ folder and treat it as application code.

3. Check whether the 3rd party library offers legacy browser support or not.

Make sure to manually keep track of improvements and bug fixes (especially security ones).

[stale]

This issue has been automatically marked as stale because it has not had any recent activity. It will be closed in 7 days if no further activity occurs.