Allow bundles to be analyzed with Webpack-specific tools #3945

joshwcomeau · 2018-01-31T13:51:10Z

Associated issue: #1858

To analyze Webpack bundles, a "stats" JSON is required.

This PR allows that file to be created and saved to the build
directory, so that users can use it with Webpack-specific insight
tools like webpack-bundle-analyzer without ejecting their
application.

Updated the README to include details for how to do this.

Test plan

1. check that the stats flag works

I ran yarn build --stats in the root directory of the project. Once it completed, I verified that build/bundle-stats.json existed. I dragged it into Webpack Visualizer to check that the file is correct:

2. check that it works in a created project

I ran yarn create-react-app test to generate a new app.

After cd-ing into the directory and installing its dependencies, I followed the steps I added to the the README for using webpack-bundle-analyzer. Specifically I ran:

$ npm install --save webpack-bundle-analyzer

Then, I opened the project's package.json and added a script:

"analyze": "npm run build -- --stats && webpack-bundle-analyzer build/bundle-stats.json",

Finally, I ran the new script:

$ npm run analyze

The project built, and a new browser window automatically opened, with the bundle stats:

joshwcomeau

Annotations

joshwcomeau · 2018-01-31T13:51:48Z

packages/react-scripts/scripts/build.js

@@ -56,6 +57,10 @@ if (!checkRequiredFiles([paths.appHtml, paths.appIndexJs])) {
  process.exit(1);
 }

+// Process CLI arguments
+const argv = process.argv.slice(2);
+const writeStatsJson = argv.indexOf('--stats') !== -1;


Not sure if stats is the best name... Open to suggestions!

I think --stats is quite nice, as it pairs well with webpack --stats flag.

joshwcomeau · 2018-01-31T13:52:53Z

packages/react-scripts/template/README.md

+
+Webpack can produce a JSON manifest that details the bundles, and several tools can use that file to do analysis.
+
+Unlike with sourcemaps, the JSON file isn't created automatically on build. You must pass a `--stats` flag, using `--` to ensure it's passed to `react-scripts`:


The last bit of the second sentence in this paragraph feels like it's too "inside baseball"; like we shouldn't need to mention what's happening with react-scripts under the hood.

But if I omit it, I worry that we aren't explaining the --, and this might cause folks to not notice it. I can imagine people being frustrated when npm run build --stats doesn't work and they can't figure out why?

Maybe there's a happy middle-ground. Open to copy suggestions.

This seems like a nice, succinct explanation to me. I don't have trouble with mentioning react-scripts here, maybe @gaearon has ideas?

I don't think -- is needed with Yarn actually, maybe it's worth to mention...

True. With yarn, we actually get a deprecation warning when using --. It might be a good idea to note it.

What's the process to merge this PR? From what I see the only required changes are on the README.md file.

I think everything after the word flag can be removed. There's an example of the full command on the next line.

valscion · 2018-02-05T09:04:21Z

packages/react-scripts/template/README.md

@@ -1972,6 +1980,44 @@ npm run build
 npm run analyze
 ```

+### Using Webpack Stats JSON


Should we add a note that this feature is available only in some specific version of react-scripts, like many other parts of the README have?

Note: this feature is available with react-scripts@x.y.z and higher.

I don't know how the process of adding these version notes goes, though. Are they added just before releasing a new version?

Yeah, good idea!

I'm also unfamiliar with the process, since yeah I don't know which version it'll be released in. Happy to update the PR if this is knowable in advance, though :)

This is going to end up in react-scripts 2.0 so it's probably a good idea to include that in the README. I'm actually not 100% on the process for this either. I don't think these notes are generated automatically so you might as well add it yourself.

Please remove this part or hide it behind comments. 2.x is the main branch now so that's what you find when you look at the repository. It will be deeply confusing to the users to see this in README now.

valscion · 2018-02-05T09:05:04Z

So cool! Thanks for working on this, it looks great to me! 💞

langpavel

Nice change, but I don't want new dependency

langpavel · 2018-02-14T17:53:36Z

packages/react-scripts/scripts/build.js

@@ -33,6 +33,7 @@ const path = require('path');
 const chalk = require('chalk');
 const fs = require('fs-extra');
 const webpack = require('webpack');
+const bfj = require('bfj');


Big Friendly JSON. Is this really needed?

langpavel · 2018-02-15T03:18:31Z

packages/react-scripts/scripts/build.js

+        return bfj
+          .write(paths.appBuild + '/bundle-stats.json', stats.toJson())
+          .then(() => resolve(resolveArgs))
+          .catch(error => reject(new Error(error)));


As I can see you don't really need BFJ because you just write only one chunk.
fs.writeFile(..., JSON.strigify(stats)) should be more effective by my opinion.

So, this was a suggestion in the issue #1858, for concerns that with very large bundles, JSON.stringify could run out of memory and crash the node process. This was reported in webpack-bundle-analyzer, where they use JSON.stringify(). bfj is streaming, so it should avoid this potential issue.

Hi @joshwcomeau, thanks for fast reply.
So if I understand, it will traverse object prepared for serialization, write it by converting text piece by piece, potentially wasting more CPU, time and memory too, but it uses small bits of memory which can be collected by GC during processing.

joshwcomeau · 2018-02-15T03:32:51Z

Hi @langpavel!

So, this was a suggestion in the issue #1858, for concerns that with very large bundles, JSON.stringify could run out of memory and crash the node process. This was reported in webpack-bundle-analyzer, where they use JSON.stringify(). bfj is streaming, so it should avoid this potential issue.

Let me know how you'd like me to proceed.

langpavel

Ok, changed my mind, BFJ may be reasonable here...

joshwcomeau · 2018-02-22T12:02:35Z

Awesome, thanks!

trevorwhealy

Looks good 👍

valscion · 2018-03-24T11:30:35Z

Anything I could do to help this PR getting merged, @gaearon? The implementation is solid and docs are good enough for the first pass. I don't see any blockers here.

kamranayub · 2018-05-03T13:58:56Z

Would be great to see this merged, went looking for this feature today 👍

joshwcomeau · 2018-05-26T14:02:52Z

Any updates on this? I understand that it's one of many open PRs, but I'd love to see this get merged.

iansu · 2018-05-27T00:40:23Z

I remember the issue discussing this but I didn't realize there was a PR this far along. I can take a look at it and test it out in the next couple of days.

iansu · 2018-05-28T18:25:18Z

This looks good to me, aside from the couple minor README changes I suggested. Based on the discussion in the linked issue it sounds like @gaearon is onboard with adding this feature so I'm happy to merge it once the docs are updated.

To analyze Webpack bundles, a "stats" JSON is required. This PR allows that file to be created and saved to the `build` directory, so that users can use it with Webpack-specific insight tools like `webpack-bundle-analyzer` without ejecting their application. Updated the README to include details for how to do this.

joshwcomeau · 2018-05-31T11:24:40Z

Updated the branch based on @iansu's comments, and rebased to deal with the conflict.

Thanks, excited to see this make it into 2.0 =)

valscion · 2018-05-31T11:36:39Z

packages/react-scripts/template/README.md

+
+The quickest way to get insight into your bundle is to drag and drop that JSON file into [Webpack Visualizer](https://chrisbateman.github.io/webpack-visualizer/).
+
+Another very popular tool is [`webpack-bundle-analyzer`](https://www.npmjs.com/package/webpack-bundle-analyzer).


Should we link to the GitHub page instead? https://github.com/webpack-contrib/webpack-bundle-analyzer

The README gets a bit squished on the https://www.npmjs.com/package/webpack-bundle-analyzer page 😕. In my opinion, the GitHub rendered page looks nicer.

In any case, this is only a nitpick and can be kept as-is ☺️

valscion · 2018-05-31T11:37:42Z

packages/react-scripts/template/README.md

+    "analyze": "npm run build -- --stats && webpack-bundle-analyzer build/bundle-stats.json",
+     "start": "react-scripts start",
+     "build": "react-scripts build",
+     "build:with-stats": "react-scripts build",


Should this build:with-stats line also have a + in the diff code example? Or should we keep the build:with-stats out from this example altogether?

Also, this example doesn't use the --stats flag correctly so it might even be incorrect?

Ah! Yeah, this is old. Will update.

valscion · 2018-05-31T11:40:09Z

So amazing to see this soon getting finished! Yay! Thank you for continuing working on this PR, @joshwcomeau 💞

joshwcomeau · 2018-06-03T13:05:28Z

@valscion made the requested changes. Good catch on build:with-stats being unnecessary!

audiolion · 2018-06-04T00:31:04Z

Looking forward to this! thanks for the work @joshwcomeau 👍

valscion

Looks great to me! 👍

gaearon · 2018-06-05T12:50:49Z

I haven't been following closely so I'll want to take another look at this before we ship 2.0.

In general I agree with #1858 (comment).

But since a lot of people want this I don't think it hurts to add this (but we might remove it in the future).

gaearon · 2018-06-05T12:53:24Z

I filed #4563 for the follow-up.

Allow bundles to be analyzed with Webpack-specific tools

facebook-github-bot added the CLA Signed label Jan 31, 2018

joshwcomeau commented Jan 31, 2018

View reviewed changes

joshwcomeau mentioned this pull request Feb 5, 2018

Allow analysis of generated bundle and dependencies #1858

Closed

valscion reviewed Feb 5, 2018

View reviewed changes

langpavel suggested changes Feb 15, 2018

View reviewed changes

langpavel approved these changes Feb 15, 2018

View reviewed changes

valscion approved these changes Feb 15, 2018

View reviewed changes

trevorwhealy approved these changes Mar 2, 2018

View reviewed changes

joshwcomeau force-pushed the bundle-stats branch from 3141500 to 7c85938 Compare May 31, 2018 11:23

valscion reviewed May 31, 2018

View reviewed changes

Remove outdated bit from README, update bundle-analyzer link

80b24d5

bugzpodder mentioned this pull request Jun 3, 2018

Solution: webpack-bundle-analyzer without ejecting. #3518

Closed

valscion approved these changes Jun 4, 2018

View reviewed changes

bugzpodder merged commit a98c3df into facebook:next Jun 4, 2018

Timer added the tag: new feature label Jun 4, 2018

Timer added this to the 2.0.0 milestone Jun 4, 2018

gaearon mentioned this pull request Jun 5, 2018

Revisit the decision to allow webpack analyzer tools #4563

Closed

marcofugaro mentioned this pull request Jun 8, 2018

Treemap for webpack statistics accurat/accurapp#20

Open

zmitry pushed a commit to zmitry/create-react-app that referenced this pull request Sep 30, 2018

Merge pull request facebook#3945 from joshwcomeau/bundle-stats

89cdb6f

Allow bundles to be analyzed with Webpack-specific tools

OzairP mentioned this pull request Jan 4, 2019

Document --stats flag and multi chunk analysis #6127

Closed

lock bot locked and limited conversation to collaborators Jan 19, 2019


		Webpack can produce a JSON manifest that details the bundles, and several tools can use that file to do analysis.

		Unlike with sourcemaps, the JSON file isn't created automatically on build. You must pass a `--stats` flag, using `--` to ensure it's passed to `react-scripts`:


		The quickest way to get insight into your bundle is to drag and drop that JSON file into [Webpack Visualizer](https://chrisbateman.github.io/webpack-visualizer/).

		Another very popular tool is [`webpack-bundle-analyzer`](https://www.npmjs.com/package/webpack-bundle-analyzer).

Allow bundles to be analyzed with Webpack-specific tools #3945

Allow bundles to be analyzed with Webpack-specific tools #3945

Conversation

joshwcomeau commented Jan 31, 2018

Test plan

joshwcomeau left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshwcomeau Jan 31, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

valscion commented Feb 5, 2018

langpavel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshwcomeau commented Feb 15, 2018 • edited Loading

langpavel left a comment

Choose a reason for hiding this comment

joshwcomeau commented Feb 22, 2018

trevorwhealy left a comment

Choose a reason for hiding this comment

valscion commented Mar 24, 2018

kamranayub commented May 3, 2018

joshwcomeau commented May 26, 2018

iansu commented May 27, 2018

iansu commented May 28, 2018

joshwcomeau commented May 31, 2018

Choose a reason for hiding this comment

valscion May 31, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

valscion commented May 31, 2018

joshwcomeau commented Jun 3, 2018

audiolion commented Jun 4, 2018

valscion left a comment

Choose a reason for hiding this comment

gaearon commented Jun 5, 2018

gaearon commented Jun 5, 2018

joshwcomeau Jan 31, 2018 •

edited

Loading

joshwcomeau commented Feb 15, 2018 •

edited

Loading

valscion May 31, 2018 •

edited

Loading