web: add Analyzing the Bundlesize check failure docs (sourcegraph#4…

…1164)
Demolicity · Sep 1, 2022 · 51b5550 · 51b5550
1 parent 8ee7590
commit 51b5550
Show file tree

Hide file tree

Showing 5 changed files with 25 additions and 2 deletions.
diff --git a/.gitignore b/.gitignore
@@ -71,6 +71,7 @@ yarn-error.log
 /ui/assets/styles/
 /ui/assets/*.br
 /ui/assets/*.gz
+/ui/assets/stats-*
 
 *.json.actual
 

diff --git a/client/build-config/src/webpack/plugins.ts b/client/build-config/src/webpack/plugins.ts
@@ -1,7 +1,11 @@
+import path from 'path'
+
 import StatoscopeWebpackPlugin from '@statoscope/webpack-plugin'
 import TerserPlugin from 'terser-webpack-plugin'
 import webpack, { StatsOptions } from 'webpack'
 
+import { STATIC_ASSETS_PATH } from '../paths'
+
 export const getTerserPlugin = (): TerserPlugin =>
     new TerserPlugin({
         terserOptions: {
@@ -46,7 +50,9 @@ const STATOSCOPE_STATS: StatsOptions = {
     performance: true, // info about oversized assets
 }
 
-export const getStatoscopePlugin = (): StatoscopeWebpackPlugin =>
+export const getStatoscopePlugin = (name = '[name]'): StatoscopeWebpackPlugin =>
     new StatoscopeWebpackPlugin({
         statsOptions: STATOSCOPE_STATS as Record<string, unknown>,
+        saveStatsTo: path.join(STATIC_ASSETS_PATH, `stats-${name}-[hash].json`),
+        saveReportTo: path.join(STATIC_ASSETS_PATH, `report-${name}-[hash].html`),
     })
diff --git a/client/web/dev/utils/environment-config.ts b/client/web/dev/utils/environment-config.ts
@@ -33,6 +33,8 @@ export const ENVIRONMENT_CONFIG = {
     WEBPACK_SERVE_INDEX: getEnvironmentBoolean('WEBPACK_SERVE_INDEX'),
     // Enables `StatoscopeWebpackPlugin` that allows to analyze application bundle.
     WEBPACK_BUNDLE_ANALYZER: getEnvironmentBoolean('WEBPACK_BUNDLE_ANALYZER'),
+    // The name used to generate Statoscope JSON stats and HTML report in the `/ui/assets` folder.
+    WEBPACK_STATS_NAME: process.env.WEBPACK_STATS_NAME,
     // Allow overriding default Webpack naming behavior for debugging
     WEBPACK_USE_NAMED_CHUNKS: getEnvironmentBoolean('WEBPACK_USE_NAMED_CHUNKS'),
 

diff --git a/client/web/webpack.config.js b/client/web/webpack.config.js
@@ -42,6 +42,7 @@ const {
   SOURCEGRAPH_API_URL,
   WEBPACK_SERVE_INDEX,
   WEBPACK_BUNDLE_ANALYZER,
+  WEBPACK_STATS_NAME,
   WEBPACK_USE_NAMED_CHUNKS,
   SENTRY_UPLOAD_SOURCE_MAPS,
   COMMIT_SHA,
@@ -162,7 +163,7 @@ const config = {
         filter: ({ isInitial, name }) => isInitial || name?.includes('react'),
       }),
     ...(WEBPACK_SERVE_INDEX ? getHTMLWebpackPlugins() : []),
-    WEBPACK_BUNDLE_ANALYZER && getStatoscopePlugin(),
+    WEBPACK_BUNDLE_ANALYZER && getStatoscopePlugin(WEBPACK_STATS_NAME),
     isHotReloadEnabled && new webpack.HotModuleReplacementPlugin(),
     isHotReloadEnabled && new ReactRefreshWebpackPlugin({ overlay: false }),
     IS_PRODUCTION &&

diff --git a/doc/dev/how-to/testing.md b/doc/dev/how-to/testing.md
@@ -496,6 +496,19 @@ If `Bundlesize` fails, it is likely because one of the generated bundles has gon
 
 If none of the above is applicable, we might need to consider adjusting our limits. Please start a discussion with @sourcegraph/frontend-devs before doing this!
 
+#### Analyzing the Bundlesize check failure
+
+To analyze web application bundles, we use [the Statoscope webpack-plugin](https://github.com/statoscope/statoscope/tree/master/packages/webpack-plugin) that generates HTML reports from webpack-stats. The best way to understand the bundlesize increase is to compare webpack-stats generated in the failing branch vs. the stats on the `main` branch. From the repo root, run the following commands:
+
+1. Install [the Statoscope CLI](https://github.com/statoscope/statoscope/tree/master/packages/cli) locally: `npm i @statoscope/cli -g`.
+2. Generate Webpack stats on the `main` branch: `WEBPACK_STATS_NAME=main yarn workspace @sourcegraph/web run analyze-bundle`.
+3. Generate Webpack stats on the failing branch: `WEBPACK_STATS_NAME=my-branch yarn workspace @sourcegraph/web run analyze-bundle`.
+4. Compare stats using Statoscope CLI: `statoscope generate -i ./ui/assets/stats-main-XXX.json -r ./ui/assets/stats-my-branch-XXX.json -o -t ./ui/assets/compare-report.html`
+5. The generated HTML report should be automatically opened in the new browser tab.
+6. Click "Diff" at the top right corner and select the `reference.json` stats.
+7. Go to "chunks" and inspect the chunk diff failing in the CI check. Clicking on the chunk should reveal the list of modules added or removed from the chunk.
+8. 🎉
+
 ### Assessing flaky client steps
 
 The breakdown of known client flakes by type with resolution tips: