1 | [![npm][npm]][npm-url]
|
2 | [![node][node]][node-url]
|
3 | [![deps][deps]][deps-url]
|
4 | [![tests][tests]][tests-url]
|
5 | [![downloads][downloads]][downloads-url]
|
6 |
|
7 | <div align="center">
|
8 | <a href="https://github.com/webpack/webpack">
|
9 | <img width="200" height="200"
|
10 | src="https://webpack.js.org/assets/icon-square-big.svg">
|
11 | </a>
|
12 | <h1>Webpack Bundle Analyzer</h1>
|
13 | <p>Visualize size of webpack output files with an interactive zoomable treemap.</p>
|
14 | </div>
|
15 |
|
16 | <h2 align="center">Install</h2>
|
17 |
|
18 | ```bash
|
19 | # NPM
|
20 | npm install --save-dev webpack-bundle-analyzer
|
21 | # Yarn
|
22 | yarn add -D webpack-bundle-analyzer
|
23 | ```
|
24 |
|
25 | <h2 align="center">Usage (as a plugin)</h2>
|
26 |
|
27 | ```js
|
28 | const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
|
29 |
|
30 | module.exports = {
|
31 | plugins: [
|
32 | new BundleAnalyzerPlugin()
|
33 | ]
|
34 | }
|
35 | ```
|
36 |
|
37 | It will create an interactive treemap visualization of the contents of all your bundles.
|
38 |
|
39 | ![webpack bundle analyzer zoomable treemap](https://cloud.githubusercontent.com/assets/302213/20628702/93f72404-b338-11e6-92d4-9a365550a701.gif)
|
40 |
|
41 | This module will help you:
|
42 |
|
43 | 1. Realize what's *really* inside your bundle
|
44 | 2. Find out what modules make up the most of its size
|
45 | 3. Find modules that got there by mistake
|
46 | 4. Optimize it!
|
47 |
|
48 | And the best thing is it supports minified bundles! It parses them to get real size of bundled modules.
|
49 | And it also shows their gzipped sizes!
|
50 |
|
51 | <h2 align="center">Options (for plugin)</h2>
|
52 |
|
53 | ```js
|
54 | new BundleAnalyzerPlugin(options?: object)
|
55 | ```
|
56 |
|
57 | |Name|Type|Description|
|
58 | |:--:|:--:|:----------|
|
59 | |**`analyzerMode`**|One of: `server`, `static`, `json`, `disabled`|Default: `server`. In `server` mode analyzer will start HTTP server to show bundle report. In `static` mode single HTML file with bundle report will be generated. In `json` mode single JSON file with bundle report will be generated. In `disabled` mode you can use this plugin to just generate Webpack Stats JSON file by setting `generateStatsFile` to `true`. |
|
60 | |**`analyzerHost`**|`{String}`|Default: `127.0.0.1`. Host that will be used in `server` mode to start HTTP server.|
|
61 | |**`analyzerPort`**|`{Number}` or `auto`|Default: `8888`. Port that will be used in `server` mode to start HTTP server.|
|
62 | |**`reportFilename`**|`{String}`|Default: `report.html`. Path to bundle report file that will be generated in `static` mode. It can be either an absolute path or a path relative to a bundle output directory (which is output.path in webpack config).|
|
63 | |**`reportTitle`**|`{String\|function}`|Default: function that returns pretty printed current date and time. Content of the HTML `title` element; or a function of the form `() => string` that provides the content.|
|
64 | |**`defaultSizes`**|One of: `stat`, `parsed`, `gzip`|Default: `parsed`. Module sizes to show in report by default. [Size definitions](#size-definitions) section describes what these values mean.|
|
65 | |**`openAnalyzer`**|`{Boolean}`|Default: `true`. Automatically open report in default browser.|
|
66 | |**`generateStatsFile`**|`{Boolean}`|Default: `false`. If `true`, webpack stats JSON file will be generated in bundle output directory|
|
67 | |**`statsFilename`**|`{String}`|Default: `stats.json`. Name of webpack stats JSON file that will be generated if `generateStatsFile` is `true`. It can be either an absolute path or a path relative to a bundle output directory (which is output.path in webpack config).|
|
68 | |**`statsOptions`**|`null` or `{Object}`|Default: `null`. Options for `stats.toJson()` method. For example you can exclude sources of your modules from stats file with `source: false` option. [See more options here](https://webpack.js.org/configuration/stats/). |
|
69 | |**`excludeAssets`**|`{null\|pattern\|pattern[]}` where `pattern` equals to `{String\|RegExp\|function}`|Default: `null`. Patterns that will be used to match against asset names to exclude them from the report. If pattern is a string it will be converted to RegExp via `new RegExp(str)`. If pattern is a function it should have the following signature `(assetName: string) => boolean` and should return `true` to *exclude* matching asset. If multiple patterns are provided asset should match at least one of them to be excluded. |
|
70 | |**`logLevel`**|One of: `info`, `warn`, `error`, `silent`|Default: `info`. Used to control how much details the plugin outputs.|
|
71 |
|
72 | <h2 align="center">Usage (as a CLI utility)</h2>
|
73 |
|
74 | You can analyze an existing bundle if you have a webpack stats JSON file.
|
75 |
|
76 | You can generate it using `BundleAnalyzerPlugin` with `generateStatsFile` option set to `true` or with this simple
|
77 | command:
|
78 |
|
79 | ```bash
|
80 | webpack --profile --json > stats.json
|
81 | ```
|
82 |
|
83 | If you're on Windows and using PowerShell, you can generate the stats file with this command to [avoid BOM issues](https://github.com/webpack-contrib/webpack-bundle-analyzer/issues/47):
|
84 |
|
85 | ```
|
86 | webpack --profile --json | Out-file 'stats.json' -Encoding OEM
|
87 | ```
|
88 |
|
89 | Then you can run the CLI tool.
|
90 |
|
91 | ```
|
92 | webpack-bundle-analyzer bundle/output/path/stats.json
|
93 | ```
|
94 |
|
95 | <h2 align="center">Options (for CLI)</h2>
|
96 |
|
97 | ```bash
|
98 | webpack-bundle-analyzer <bundleStatsFile> [bundleDir] [options]
|
99 | ```
|
100 |
|
101 | Arguments are documented below:
|
102 |
|
103 | ### `bundleStatsFile`
|
104 |
|
105 | Path to webpack stats JSON file
|
106 |
|
107 | ### `bundleDir`
|
108 |
|
109 | Directory containing all generated bundles.
|
110 |
|
111 | ### `options`
|
112 |
|
113 | ```
|
114 | -V, --version output the version number
|
115 | -m, --mode <mode> Analyzer mode. Should be `server`, `static` or `json`.
|
116 | In `server` mode analyzer will start HTTP server to show bundle report.
|
117 | In `static` mode single HTML file with bundle report will be generated.
|
118 | In `json` mode single JSON file with bundle report will be generated. (default: server)
|
119 | -h, --host <host> Host that will be used in `server` mode to start HTTP server. (default: 127.0.0.1)
|
120 | -p, --port <n> Port that will be used in `server` mode to start HTTP server. Should be a number or `auto` (default: 8888)
|
121 | -r, --report <file> Path to bundle report file that will be generated in `static` mode. (default: report.html)
|
122 | -t, --title <title> String to use in title element of html report. (default: pretty printed current date)
|
123 | -s, --default-sizes <type> Module sizes to show in treemap by default.
|
124 | Possible values: stat, parsed, gzip (default: parsed)
|
125 | -O, --no-open Don't open report in default browser automatically.
|
126 | -e, --exclude <regexp> Assets that should be excluded from the report.
|
127 | Can be specified multiple times.
|
128 | -l, --log-level <level> Log level.
|
129 | Possible values: debug, info, warn, error, silent (default: info)
|
130 | -h, --help output usage information
|
131 | ```
|
132 |
|
133 | <h2 align="center" id="size-definitions">Size definitions</h2>
|
134 |
|
135 | webpack-bundle-analyzer reports three values for sizes. `defaultSizes` can be used to control which of these is shown by default. The different reported sizes are:
|
136 |
|
137 | ### `stat`
|
138 |
|
139 | This is the "input" size of your files, before any transformations like
|
140 | minification.
|
141 |
|
142 | It is called "stat size" because it's obtained from Webpack's
|
143 | [stats object](https://webpack.js.org/configuration/stats/).
|
144 |
|
145 | ### `parsed`
|
146 |
|
147 | This is the "output" size of your files. If you're using a Webpack plugin such
|
148 | as Uglify, then this value will reflect the minified size of your code.
|
149 |
|
150 | ### `gzip`
|
151 |
|
152 | This is the size of running the parsed bundles/modules through gzip compression.
|
153 |
|
154 | <h2 align="center">Selecting Which Chunks to Display</h2>
|
155 |
|
156 | When opened, the report displays all of the Webpack chunks for your project. It's possible to filter to a more specific list of chunks by using the sidebar or the chunk context menu.
|
157 |
|
158 | ### Sidebar
|
159 |
|
160 | The Sidebar Menu can be opened by clicking the `>` button at the top left of the report. You can select or deselect chunks to display under the "Show chunks" heading there.
|
161 |
|
162 | ### Chunk Context Menu
|
163 |
|
164 | The Chunk Context Menu can be opened by right-clicking or `Ctrl`-clicking on a specific chunk in the report. It provides the following options:
|
165 |
|
166 | * **Hide chunk:** Hides the selected chunk
|
167 | * **Hide all other chunks:** Hides all chunks besides the selected one
|
168 | * **Show all chunks:** Un-hides any hidden chunks, returning the report to its initial, unfiltered view
|
169 |
|
170 | <h2 align="center">Troubleshooting</h2>
|
171 |
|
172 | ### I don't see `gzip` or `parsed` sizes, it only shows `stat` size
|
173 |
|
174 | It happens when `webpack-bundle-analyzer` analyzes files that don't actually exist in your file system, for example when you work with `webpack-dev-server` that keeps all the files in RAM. If you use `webpack-bundle-analyzer` as a plugin you won't get any errors, however if you run it via CLI you get the error message in terminal:
|
175 | ```
|
176 | Couldn't parse bundle asset "your_bundle_name.bundle.js".
|
177 | Analyzer will use module sizes from stats file.
|
178 | ```
|
179 | To get more information about it you can read [issue #147](https://github.com/webpack-contrib/webpack-bundle-analyzer/issues/147).
|
180 |
|
181 | <h2 align="center">Other tools</h2>
|
182 |
|
183 | - [Statoscope](https://github.com/smelukov/statoscope/blob/master/packages/ui-webpack/README.md) - Webpack bundle analyzing tool to find out why a certain module was bundled (and more features, including interactive treemap)
|
184 |
|
185 | <h2 align="center">Maintainers</h2>
|
186 |
|
187 | <table>
|
188 | <tbody>
|
189 | <tr>
|
190 | <td align="center">
|
191 | <img width="150" height="150"
|
192 | src="https://avatars3.githubusercontent.com/u/302213?v=4&s=150">
|
193 | </br>
|
194 | <a href="https://github.com/th0r">Yuriy Grunin</a>
|
195 | </td>
|
196 | <td align="center">
|
197 | <img width="150" height="150"
|
198 | src="https://avatars3.githubusercontent.com/u/482561?v=4&s=150">
|
199 | </br>
|
200 | <a href="https://github.com/valscion">Vesa Laakso</a>
|
201 | </td>
|
202 | </tr>
|
203 | <tbody>
|
204 | </table>
|
205 |
|
206 |
|
207 | [npm]: https://img.shields.io/npm/v/webpack-bundle-analyzer.svg
|
208 | [npm-url]: https://npmjs.com/package/webpack-bundle-analyzer
|
209 |
|
210 | [node]: https://img.shields.io/node/v/webpack-bundle-analyzer.svg
|
211 | [node-url]: https://nodejs.org
|
212 |
|
213 | [deps]: https://david-dm.org/webpack-contrib/webpack-bundle-analyzer.svg
|
214 | [deps-url]: https://david-dm.org/webpack-contrib/webpack-bundle-analyzer
|
215 |
|
216 | [tests]: http://img.shields.io/travis/webpack-contrib/webpack-bundle-analyzer.svg
|
217 | [tests-url]: https://travis-ci.org/webpack-contrib/webpack-bundle-analyzer
|
218 |
|
219 | [downloads]: https://img.shields.io/npm/dt/webpack-bundle-analyzer.svg
|
220 | [downloads-url]: https://npmjs.com/package/webpack-bundle-analyzer
|
221 |
|
222 | <h2 align="center">Contributing</h2>
|
223 |
|
224 | Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on contributing :tada:
|