-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
344 lines (329 loc) · 12 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>JSDoc: Home</title>
<script src="scripts/prettify/prettify.js"></script>
<script src="scripts/prettify/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link
type="text/css"
rel="stylesheet"
href="styles/prettify-tomorrow.css"
/>
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css" />
</head>
<body>
<div id="main">
<h1 class="page-title">Home</h1>
<h3></h3>
<section>
<article>
<h1>Build sizes</h1>
<p>
A small script that provides build sizes to assist with
optimization.
</p>
<br />
<div align="center">
<b>🚀 Zero dependencies! 🚀</b>
</div>
<h2>Installation</h2>
<p>
Install
<a href="https://www.npmjs.com/package/build-sizes">the package</a>
globally and use it anywhere:
</p>
<pre class="prettyprint source lang-sh"><code>npm i -g build-sizes
</code></pre>
<p>Use it in a single application:</p>
<pre class="prettyprint source lang-sh"><code>npm i -D build-sizes
</code></pre>
<p>Or try it out before installing:</p>
<pre
class="prettyprint source lang-sh"
><code>npx build-sizes your/build/directory
</code></pre>
<br />
<h2>Using the CLI</h2>
<p>
To run the script, you need to provide the path (absolute or
relative) to the application's build directory. For example,
<code>create-react-app</code> generates a directory named
<code>build</code> for production (other common names include
<code>dist</code> and <code>public</code>). After building the
application, you can get the sizes by running the following from the
application's root directory:
</p>
<pre class="prettyprint source lang-sh"><code>build-sizes build
</code></pre>
<p>And the output to the console is:</p>
<pre
class="prettyprint source lang-sh"
><code>-----------------------------
|> Application Build Sizes <|
-----------------------------
Build
--> file count: 419
--> size: 27.73 MB
-----------------------------
Main JS bundle
--> name: main.6e924e92.js
--> size: 1.70 MB
--> gzip size: 462.92 KB
--> brotli size: 375.26 KB
-----------------------------
</code></pre>
<blockquote>
<p>
<strong>NOTE:</strong> The "main bundle" file is naively
chosen by largest file size, it doesn't use a dependency graph.
This script is minimal by design, check out
<a
href="https://github.com/webpack-contrib/webpack-bundle-analyzer"
><code>webpack-bundle-analyzer</code></a
>
for a more complex bundle size tool.
</p>
</blockquote>
<p>
Flags are provided to change the default options. For example, you
can specify a filetype for the largest bundle size (default is
"js"):
</p>
<pre
class="prettyprint source lang-sh"
><code>build-sizes dist --filetype=css
</code></pre>
<p>
The argument parsing logic is very simple and requires the equals
sign (<code>=</code>) between the flag and its value. Additionally,
short flags cannot be grouped together into a single argument. Here
are a couple examples of what will and won't work:
</p>
<pre
class="prettyprint source lang-sh"
><code># These two are incorrect
build-sizes dist -lb # -l and -b flags combined into a single argument
build-sizes dist --decimals 4 # space between --decimals flag and its value
# This one is correct
build-sizes dist -l -b --decimals=4
</code></pre>
<p>
The <code>-h</code> or <code>--help</code> flag will log usage
information to the console, copy/pasted here for convenience:
</p>
<details>
<summary>Usage info</summary>
<h3>Arguments</h3>
<p><strong>path [required]</strong></p>
<ul>
<li>Path to the build directory</li>
</ul>
<h3>Options</h3>
<p><strong>-l, --loader [boolean]</strong></p>
<ul>
<li>Show a loading animation while determining the build size</li>
</ul>
<p><strong>-b, --binary [boolean]</strong></p>
<ul>
<li>
Convert bytes to human readable format in base 2 instead of base
10
</li>
</ul>
<p><strong>-d, --decimals</strong></p>
<ul>
<li>
Number of decimal places for rounding bytes to a human readable
format (default is 2)
</li>
</ul>
<p><strong>-f, --filetype</strong></p>
<ul>
<li>Filetype of the main bundle (default is js)</li>
</ul>
<p><strong>-o, --outfile</strong></p>
<ul>
<li>Path to a file for saving build sizes as CSV data</li>
</ul>
<p><strong>-p, --path [required]</strong></p>
<ul>
<li>Path to the build directory (also available as argument)</li>
</ul>
<h3>Examples</h3>
<ul>
<li>
<p>Simplest usage with sane defaults</p>
<pre class="prettyprint source lang-sh"><code>build-sizes dist
</code></pre>
</li>
<li>
<p>
Size of the largest css file with tweaked number formatting
</p>
<pre
class="prettyprint source lang-sh"
><code>build-sizes dist --filetype=css --binary --decimals=1
</code></pre>
</li>
<li>
<p>
Same as above, but use a flag for path when it's not the first
argument
</p>
<pre
class="prettyprint source lang-sh"
><code>build-sizes -f=css -b -d=1 -p=dist
</code></pre>
</li>
<li>
<p>Save the build sizes to a csv</p>
<pre
class="prettyprint source lang-sh"
><code>build-sizes dist --outfile=data/build-sizes.csv
</code></pre>
</li>
</ul>
</details>
<br />
<h3>Running from an npm script</h3>
<p>
Pro tip: you can view the sizes after every build by adding a
<code>postbuild</code> npm script:
</p>
<pre
class="prettyprint source lang-diff"
><code> "scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
+ "postbuild": "build-sizes build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},
...
</code></pre>
<p>
The sizes will be logged to the console after running
<code>npm run build</code>.
</p>
<br />
<h2>Using the functions</h2>
<p>
The package also exports functions,
<a href="https://benelan.github.io/build-sizes/global.html"
>documented here</a
>. They are available as both CommonJS and ECMAScript modules. Check
out the
<a
href="https://github.com/benelan/build-sizes/blob/master/src/cli.js"
>CLI code</a
>
for a simple usage example that logs build sizes to the console.
Here is another usage example that saves your project's build sizes,
version, and a timestamp to a CSV file.
</p>
<pre
class="prettyprint source lang-js"
><code>import { appendFile, readFile, writeFile } from "fs/promises";
import { getBuildSizes } from "build-sizes";
const ARGUMENT_ERROR = `Two required arguments (in order):
- path to the build directory
- path of the output csv file`;
(async () => {
try {
const [build, outfile] = process.argv.splice(2);
if (!build || !outfile) throw new Error(ARGUMENT_ERROR);
const sizes = await getBuildSizes(build);
const version = JSON.parse(await readFile("package.json", "utf8")).version;
// convert build-sizes output into csv header and row
const header = ["Version", "Timestamp", ...Object.keys(sizes)]
.join(",")
.concat("\n");
const row = [version, Date.now(), ...Object.values(sizes)]
.join(",")
.concat("\n");
try {
// write csv header if outfile doesn't exist
await writeFile(outfile, header, { flag: "wx" });
} catch (err) {
// don't throw error if outfile does exists
if (err.code !== "EEXIST") {
throw new Error(err);
}
}
// append build size info to csv
await appendFile(outfile, row);
} catch (err) {
console.error(err);
process.exit(1);
}
})();
</code></pre>
<p>
You can use the example by providing the paths to the build
directory and output CSV file:
</p>
<pre
class="prettyprint source lang-sh"
><code>node save.js dist sizes.csv
</code></pre>
<p>
You could even add it as a <code>postpublish</code> script to keep
track of your build sizes for each release! As a matter of fact,
scratch that I'm adding it to the package 🚀
</p>
<p>
Use the <code>-o</code> or <code>--outfile</code> flag to specify
the CSV file's location:
</p>
<pre
class="prettyprint source lang-diff"
><code> "scripts": {
"publish": "... && npm publish",
+ "postpublish": "build-sizes dist -o=sizes.csv",
...
</code></pre>
<p>
The <code>saveBuildSizes</code> function is also exported, so you
can use it in your scripts!
</p>
<blockquote>
<p>
<strong>Note:</strong> The save script requires the current
working directory to contain <code>package.json</code> so it can
grab the project's version number. I recommend using an npm script
like the snippet above, which allows you to run the script from
any directory in the project.
</p>
</blockquote>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2>
<h3>Global</h3>
<ul>
<li><a href="global.html#filterFilesByType">filterFilesByType</a></li>
<li><a href="global.html#formatBytes">formatBytes</a></li>
<li><a href="global.html#getBuildSizes">getBuildSizes</a></li>
<li><a href="global.html#getFileSizeBrotli">getFileSizeBrotli</a></li>
<li><a href="global.html#getFileSizeGzip">getFileSizeGzip</a></li>
<li><a href="global.html#getFiles">getFiles</a></li>
<li><a href="global.html#saveBuildSizes">saveBuildSizes</a></li>
</ul>
</nav>
<br class="clear" />
<footer>
Documentation generated by
<a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Thu Apr 25
2024 05:02:04 GMT-0700 (Pacific Daylight Time)
</footer>
<script>
prettyPrint();
</script>
<script src="scripts/linenumber.js"></script>
</body>
</html>