Document --stats flag and multi chunk analysis

[OzairP]

Finalized page screenshot can be seen here

Documenting --stats

This PR will document a feature released in 2.0.3 which is the --stats flag that outputs the generated Webpack stats file (#3945).

Documenting multi chunk analysis

It also documents a method to analyze a bundle that contains multiple chunks (i.e. code split) since source-map-analyzer does not support multiple files by using webpack-bundle-analyzer instead.

Page structure change

Since the page does not contain one section anymore I expanded it into a introduction on bundle analysis and named the original section "Getting Started".

Notes

I double checked to make sure I followed consistency and styling but let me know if theres any thing I can align with the current code base :)

When posting this hidden feature to Reddit it looks like many people did not know about it either!
https://www.reddit.com/r/reactjs/comments/a6drwr/til_in_cra2_you_can_pass_stats_flag_to_generate/

[facebook-github-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need the corporate CLA signed.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[Timer]

n.b. this flag was intentionally undocumented because it'll be removed in a future release.

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[OzairP]

@Timer

I read through the discussion in #4563. The discussion seems to still be open so has the CRA team committed to removing the flag/feature? The discussion is mostly around webpack-bundle-analyzer and not the stats file itself it seems so I am not sure why it is being removed, perhaps that discussion belongs in the thread however.

I personally do not think it is worth hiding this extremely useful feature.

If the CRA team is still not pleased with the reporting that the tool does what do you think about adding a warning in the Analyzing Multi-Chunk Bundle Sizes section about possible discrepancies?
Removing the section as a whole is also an option however I think the usefulness of the tool outweighs its disadvantages.

The stats file however is agnostic to the analysis tool so that should at least be kept in the documentation. At the very least, the stats flag should be documented with a warning of its removal in the future since it is after all in the current release.

I do not have any numbers but I would confidently guess a large number of React applications utilize code splitting, and source map explorer does not work with chunks at all. You would have to individually analyze each chunk independently which is a major hassle and does not show the complete picture.

[OzairP]

@Timer any movement on the state of this flag?

[stale]

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

[stale]

This pull request has been automatically closed because it has not had any recent activity. If you have a question or comment, please open a new issue. Thank you for your contribution!