@bymaksym/loadline 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +182 -0
- package/bin/loadline.js +50 -0
- package/dist/cli/cli/args.js +324 -0
- package/dist/cli/cli/args.types.js +3 -0
- package/dist/cli/cli/gates.js +173 -0
- package/dist/cli/cli/gates.types.js +3 -0
- package/dist/cli/cli/main.js +156 -0
- package/dist/cli/cli/read-build.js +382 -0
- package/dist/cli/cli/read-build.types.js +3 -0
- package/dist/cli/cli/render-json.js +116 -0
- package/dist/cli/cli/render-json.types.js +10 -0
- package/dist/cli/cli/render-markdown.js +30 -0
- package/dist/cli/cli/render-pr.js +76 -0
- package/dist/cli/cli/render-sarif.js +83 -0
- package/dist/cli/cli/render-text.js +388 -0
- package/dist/cli/cli/report.js +196 -0
- package/dist/cli/cli/report.types.js +3 -0
- package/dist/cli/cli/self-check.js +85 -0
- package/dist/cli/cli/text.js +180 -0
- package/dist/cli/cli/text.types.js +10 -0
- package/dist/cli/src/app/core/analysis/analysis.js +661 -0
- package/dist/cli/src/app/core/analysis/analysis.types.js +6 -0
- package/dist/cli/src/app/core/analysis/barrels.js +128 -0
- package/dist/cli/src/app/core/analysis/blast.js +172 -0
- package/dist/cli/src/app/core/analysis/cycles.js +110 -0
- package/dist/cli/src/app/core/analysis/delivery.js +143 -0
- package/dist/cli/src/app/core/analysis/entries.js +217 -0
- package/dist/cli/src/app/core/analysis/exclusive.js +91 -0
- package/dist/cli/src/app/core/analysis/importers.js +38 -0
- package/dist/cli/src/app/core/analysis/insights.js +202 -0
- package/dist/cli/src/app/core/analysis/insights.types.js +10 -0
- package/dist/cli/src/app/core/analysis/invariant.js +69 -0
- package/dist/cli/src/app/core/analysis/metafile.types.js +44 -0
- package/dist/cli/src/app/core/analysis/module-graph.js +192 -0
- package/dist/cli/src/app/core/analysis/sourcemap.js +231 -0
- package/dist/cli/src/app/core/analysis/sourcemap.types.js +3 -0
- package/dist/cli/src/app/core/analysis/split-drift.js +47 -0
- package/dist/cli/src/app/core/assets/assets.js +296 -0
- package/dist/cli/src/app/core/assets/assets.types.js +11 -0
- package/dist/cli/src/app/core/baseline/baseline.js +0 -0
- package/dist/cli/src/app/core/baseline/baseline.types.js +3 -0
- package/dist/cli/src/app/core/caching/caching.js +241 -0
- package/dist/cli/src/app/core/caching/caching.types.js +10 -0
- package/dist/cli/src/app/core/caching/from-analysis.js +73 -0
- package/dist/cli/src/app/core/config/loadline-config.js +110 -0
- package/dist/cli/src/app/core/config/loadline-config.types.js +12 -0
- package/dist/cli/src/app/core/criteria/criteria.js +228 -0
- package/dist/cli/src/app/core/criteria/criteria.types.js +3 -0
- package/dist/cli/src/app/core/deps/deps.js +225 -0
- package/dist/cli/src/app/core/deps/deps.types.js +15 -0
- package/dist/cli/src/app/core/export/markdown-table.utils.js +40 -0
- package/dist/cli/src/app/core/export/summary.js +72 -0
- package/dist/cli/src/app/core/findings/actions.js +59 -0
- package/dist/cli/src/app/core/findings/assets.js +130 -0
- package/dist/cli/src/app/core/findings/caching.js +165 -0
- package/dist/cli/src/app/core/findings/compose.js +41 -0
- package/dist/cli/src/app/core/findings/deps.js +66 -0
- package/dist/cli/src/app/core/findings/effort.js +117 -0
- package/dist/cli/src/app/core/findings/finding-html.js +13 -0
- package/dist/cli/src/app/core/findings/finding-plain.js +26 -0
- package/dist/cli/src/app/core/findings/finding-text.js +1231 -0
- package/dist/cli/src/app/core/findings/finding.types.js +80 -0
- package/dist/cli/src/app/core/findings/findings.js +514 -0
- package/dist/cli/src/app/core/findings/graph.js +167 -0
- package/dist/cli/src/app/core/findings/own-in-boot.js +88 -0
- package/dist/cli/src/app/core/findings/page.js +49 -0
- package/dist/cli/src/app/core/findings/requests.js +185 -0
- package/dist/cli/src/app/core/findings/scan.js +126 -0
- package/dist/cli/src/app/core/findings/shipped.js +244 -0
- package/dist/cli/src/app/core/findings/situation.js +116 -0
- package/dist/cli/src/app/core/format/format.utils.js +204 -0
- package/dist/cli/src/app/core/i18n/en.js +819 -0
- package/dist/cli/src/app/core/i18n/es.js +822 -0
- package/dist/cli/src/app/core/i18n/ui-strings.js +11 -0
- package/dist/cli/src/app/core/i18n/ui.js +7 -0
- package/dist/cli/src/app/core/intake/bundle-graph.js +346 -0
- package/dist/cli/src/app/core/intake/bundle-graph.types.js +3 -0
- package/dist/cli/src/app/core/intake/dist-files.js +160 -0
- package/dist/cli/src/app/core/intake/index-html.js +292 -0
- package/dist/cli/src/app/core/json/json.utils.js +55 -0
- package/dist/cli/src/app/core/measurement/measurement.types.js +14 -0
- package/dist/cli/src/app/core/project/budget-advice.js +76 -0
- package/dist/cli/src/app/core/project/project-context.js +394 -0
- package/dist/cli/src/app/core/project/project-context.types.js +3 -0
- package/dist/cli/src/app/core/scan/catalog.js +67 -0
- package/dist/cli/src/app/core/scan/scan.js +280 -0
- package/dist/cli/src/app/core/scan/scan.types.js +10 -0
- package/dist/cli/src/app/core/scan/secrets.js +0 -0
- package/dist/cli/src/app/core/situation/situation.js +261 -0
- package/dist/cli/src/app/core/situation/situation.types.js +19 -0
- package/dist/cli/src/app/core/timing/timing.js +87 -0
- package/dist/cli/src/app/core/timing/timing.types.js +3 -0
- package/dist/cli/src/app/core/whatif/defer.js +68 -0
- package/dist/cli/src/app/state/report-messages.utils.js +73 -0
- package/docs/HOW-IT-WORKS.md +1087 -0
- package/loadline.html +78 -0
- package/package.json +154 -0
|
@@ -0,0 +1,1087 @@
|
|
|
1
|
+
# How Loadline works
|
|
2
|
+
|
|
3
|
+
[← Back to the README](../README.md)
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. The idea
|
|
8
|
+
|
|
9
|
+
The browser does not download your project. It downloads a handful of JavaScript files your bundler
|
|
10
|
+
built by fusing hundreds of source files together, and how it grouped them decides whether opening
|
|
11
|
+
the app costs 400 kB or 900 kB. Loadline reconstructs that grouping and reports it **per screen**
|
|
12
|
+
rather than per file.
|
|
13
|
+
|
|
14
|
+
There are two ways one file can reach another, and they mean opposite things:
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import { thing } from './b'; // static: A and B always travel TOGETHER
|
|
18
|
+
const { thing } = await import('./b'); // dynamic: B travels separately
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
| Group | What it is | When it downloads |
|
|
22
|
+
| ---------------------------------- | ------------------------------------------------- | ------------------------- |
|
|
23
|
+
| **Bootstrap** (`initial`, `eager`) | Reachable from the entry point via static imports | Always |
|
|
24
|
+
| **Lazy** | Whatever hangs off a dynamic import | When that code is reached |
|
|
25
|
+
|
|
26
|
+
In Angular, `loadComponent`, `loadChildren` and `@defer` are dynamic imports; everything else is
|
|
27
|
+
static.
|
|
28
|
+
|
|
29
|
+
**The blind spot.** When two lazy screens use the same thing, the bundler does not duplicate it — it
|
|
30
|
+
builds a third, shared chunk, which appears in the lazy list. If every screen imports that chunk, it
|
|
31
|
+
downloads every time anyway. Counting how many screens reach each chunk is what the rest of this
|
|
32
|
+
document is built on.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 2. The algorithm
|
|
37
|
+
|
|
38
|
+
Everything comes from one graph: which source file ended up in which chunk, how many bytes each
|
|
39
|
+
contributes, and who imports whom. The esbuild metafile records it directly; a build folder is read
|
|
40
|
+
for it instead when there is no metafile (§5). From here on the two are the same thing — the
|
|
41
|
+
algorithm never learns which one it got.
|
|
42
|
+
|
|
43
|
+
### 2.1 Reachability over static imports
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
const reach = start => {
|
|
47
|
+
const seen = new Set();
|
|
48
|
+
const stack = [start];
|
|
49
|
+
while (stack.length) {
|
|
50
|
+
const file = stack.pop();
|
|
51
|
+
if (!file || seen.has(file) || !outputs[file]) continue;
|
|
52
|
+
seen.add(file);
|
|
53
|
+
for (const imp of outputs[file].imports || []) {
|
|
54
|
+
if (imp.kind === 'import-statement') stack.push(imp.path); // <- static only
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return seen;
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Filtering on `import-statement` is the whole trick. A `dynamic-import` is the lazy boundary:
|
|
62
|
+
following it would merge everything and report the entire bundle every time.
|
|
63
|
+
|
|
64
|
+
### 2.2 Finding the main entry
|
|
65
|
+
|
|
66
|
+
An output is a **lazy entry** when some other output has a `dynamic-import` pointing at it. The main
|
|
67
|
+
entry is one that is not. Several candidates can exist — some libraries emit a stray entry, such as a
|
|
68
|
+
worker — so the one reaching the most code wins:
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
const mainChunk = rootCandidates.map(([k]) => [k, reach(k).size]).sort((a, b) => b[1] - a[1])[0][0];
|
|
72
|
+
const alsoStarted = rootCandidates.filter(([k]) => k !== mainChunk && announced.has(baseName(k)));
|
|
73
|
+
const initial = new Set([mainChunk, ...alsoStarted.map(([k]) => k)].flatMap(k => [...reach(k)]));
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
⚠️ **An application does not have to have one entry chunk.** Angular's polyfills are a second one and
|
|
77
|
+
SvelteKit starts two, its router and the application, from a script inside the page. Taking the main
|
|
78
|
+
one alone left real bootstrap chunks out of the figure everybody pays. What decides is the page: an
|
|
79
|
+
entry nobody announces is not downloaded on the first load and stays out, which is what keeps the
|
|
80
|
+
worker out.
|
|
81
|
+
|
|
82
|
+
### 2.3 Detecting screens
|
|
83
|
+
|
|
84
|
+
Lazy entries whose `entryPoint` is your own code:
|
|
85
|
+
|
|
86
|
+
```js
|
|
87
|
+
const routes = entries
|
|
88
|
+
.filter(([k]) => lazyTargets.has(k))
|
|
89
|
+
.filter(r => !/node_modules/.test(r.source)) // xlsx, pdf.js: not screens
|
|
90
|
+
.filter(r => !/\.routes?\.(t|j)s$/.test(r.source)); // grouping files own nothing
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
⚠️ **Both filters came out of testing.** Without the first, `FileSaver.min` and `xlsx` showed up as
|
|
94
|
+
screens — an `await import('xlsx')` produces a lazy entry too. Without the second, routing files
|
|
95
|
+
clutter the list with rows that are nobody's screen.
|
|
96
|
+
|
|
97
|
+
Three more rules joined them:
|
|
98
|
+
|
|
99
|
+
- **A lazy entry that only views import lazily is a piece of a screen, not a screen.** This is the
|
|
100
|
+
rule that keeps the table honest as `@defer` spreads; see §5.
|
|
101
|
+
- **A screen has to be reachable from where the application starts**, following both kinds of import.
|
|
102
|
+
A folder nobody cleans still holds the previous build, and those old chunks were taking rows in the
|
|
103
|
+
table while none of their bytes appeared in any figure.
|
|
104
|
+
- **Data is not a screen.** `import('./locales/ru-RU.json')` produces a lazy entry exactly like a
|
|
105
|
+
route does. Excalidraw lazy-loads fifty languages, and its table came out with sixty-one rows for
|
|
106
|
+
an application with one screen. Data entries are listed separately.
|
|
107
|
+
|
|
108
|
+
### 2.4 Splitting the cost
|
|
109
|
+
|
|
110
|
+
For each screen: what it reaches, minus the bootstrap, split into what only it loads and what it
|
|
111
|
+
shares.
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
const lazy = [...r.set].filter(c => !initial.has(c));
|
|
115
|
+
const own = lazy.filter(c => routeCount.get(c) === 1);
|
|
116
|
+
const shared = lazy.filter(c => routeCount.get(c) > 1);
|
|
117
|
+
const total = bootBytes + sumOf(lazy);
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`routeCount` — how many screens reach each chunk — is the figure the whole tool is built around.
|
|
121
|
+
|
|
122
|
+
### 2.5 Compressing
|
|
123
|
+
|
|
124
|
+
Each file in the build folder is gzipped in the browser with the native API:
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
const stream = file.stream().pipeThrough(new CompressionStream('gzip'));
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
**At which level.** zlib's default, 6. `CompressionStream('gzip')` in the browser and `createGzip()`
|
|
131
|
+
in the command are the same library at the same setting, which is why the page and the terminal print
|
|
132
|
+
the same figure for the same file, and it is what nginx, Apache and most CDNs serve at by default. A
|
|
133
|
+
server tuned to 9 sends slightly less and one tuned to 1 slightly more — a few per cent, in the same
|
|
134
|
+
direction for every file, so it moves the headline and not the ordering.
|
|
135
|
+
|
|
136
|
+
**What is compressed is the file, never its parts.** Gzip works on the whole chunk, using repetitions
|
|
137
|
+
that cross from one module into the next, so "the compressed weight of `date-fns` inside this chunk"
|
|
138
|
+
is not a quantity that exists. The breakdown inside a chunk is therefore always raw, even while the
|
|
139
|
+
report is in compressed figures. To keep the two units from being confused, the chunk's row carries
|
|
140
|
+
its raw size under the compressed one, and the head of its file tree says `raw` and how much of the
|
|
141
|
+
chunk is unattributed. Those bytes are the bundler's own code — module wrapper, banners — which
|
|
142
|
+
belongs to no input file. The sum of the files plus that remainder is the raw size on the row, when
|
|
143
|
+
the two measurements agree, which is checked rather than assumed (§3.23). Other tools
|
|
144
|
+
(`esbuild-visualizer`, Sonda) show the raw figure as the chunk's headline, which is why their numbers
|
|
145
|
+
look nothing like Loadline's until both are read in the same unit.
|
|
146
|
+
|
|
147
|
+
**Brotli.** The browser cannot compress in brotli: `CompressionStream` offers gzip and deflate only.
|
|
148
|
+
`brotli-wasm` ships 1,057 kB of `.wasm`, almost three times the whole of Loadline, and in a
|
|
149
|
+
self-contained HTML file that is paid in base64 — measured and dropped. What works instead: when the
|
|
150
|
+
folder brings pre-compressed `main-ABC.js.br` files, their size on disk **is** the brotli figure, with
|
|
151
|
+
nothing to decompress. Both figures are then available and Criteria picks which drives the report;
|
|
152
|
+
the brotli thresholds are the gzip ones minus 15 %, which is how much more it compresses (measured on
|
|
153
|
+
this build: 0.865 and 0.856). Without `.br` in the folder, the Criteria tab warns that a red just
|
|
154
|
+
above the threshold may not be red in production.
|
|
155
|
+
|
|
156
|
+
### 2.6 Searching by name
|
|
157
|
+
|
|
158
|
+
The rest of the report answers _what is heavy_. The question that actually turns up is the other way
|
|
159
|
+
round — "are we still shipping `moment`?" — and it used to mean opening chunk after chunk.
|
|
160
|
+
|
|
161
|
+
The index is built once per analysis from what is already in memory: every file that ships bytes,
|
|
162
|
+
with the chunks it lands in. Files under `node_modules` are grouped by package, because that is the
|
|
163
|
+
unit a decision is taken about; project files stay one per file, because that is the unit that gets
|
|
164
|
+
edited. A package also matches on the names of its files, so `md5` finds `crypto-js`.
|
|
165
|
+
|
|
166
|
+
Each result says which chunks carry it, how much in each, which screens load it, and the import chain
|
|
167
|
+
that brings it in. Two details that came out of real use:
|
|
168
|
+
|
|
169
|
+
- **The zone is that of the heaviest chunk, not the worst one.** PrimeNG landed in five chunks of one
|
|
170
|
+
app: 612 kB in a shared one and 145 kB in the bootstrap. Calling it "bootstrap" would say every load
|
|
171
|
+
pays 772 kB for it, and it pays 145. It says "shared", and underneath, how much falls in the
|
|
172
|
+
bootstrap.
|
|
173
|
+
- **Finding nothing is an answer.** "Nothing called _moment_ is in the bundle" could not previously be
|
|
174
|
+
established without walking everything and still being unsure.
|
|
175
|
+
|
|
176
|
+
### 2.7 What a shared chunk costs, and where the cost comes from
|
|
177
|
+
|
|
178
|
+
A tab saying "58 kB across 44 of 47 screens" leaves the reader with the next question: is that as bad
|
|
179
|
+
as it looks, and which part of it is the weight? Three things can be computed for it
|
|
180
|
+
(`core/worth/worth.ts`).
|
|
181
|
+
|
|
182
|
+
**What it really costs: size × coverage.** 58 kB loaded by 44 of 47 screens costs 54 kB on a typical
|
|
183
|
+
visit; the same 58 kB loaded by 5 of them costs 6 kB. Same row in the size column, ten times the cost.
|
|
184
|
+
That weighted figure is what the report ranks and prices with, and next to it goes what a typical
|
|
185
|
+
visit would weigh with the chunk gone — the ceiling of any fix.
|
|
186
|
+
|
|
187
|
+
**Splitting a shared chunk saves nothing.** esbuild builds one chunk per distinct set of entry points
|
|
188
|
+
that reach a module, so every file inside a chunk is reached by exactly the same screens; cutting it
|
|
189
|
+
in two produces two chunks the same screens load. This follows from how the split is made, and it
|
|
190
|
+
retires the first idea most people have on seeing the tab. What lowers the figure is fewer screens
|
|
191
|
+
importing the thing, or the thing weighing less.
|
|
192
|
+
|
|
193
|
+
**Where the weight comes from** depends on what the chunk carries, and the analysis already groups it
|
|
194
|
+
by package and by project folder:
|
|
195
|
+
|
|
196
|
+
| What dominates it (≥ 50 %) | Tag | Because |
|
|
197
|
+
| ------------------------------------- | ---------------------- | ----------------------------------------------------------------------- |
|
|
198
|
+
| Nothing — the cost is under the floor | Below the threshold | The gain is lost between any two builds |
|
|
199
|
+
| A folder of your own code | Your own code | Nothing to negotiate: usually a barrel file re-exporting a whole folder |
|
|
200
|
+
| A package few of your files import | 1 package · N of yours | Few importers is an address: one place to check whether it is needed |
|
|
201
|
+
| A package imported from all over | No dominant source | No single file to point at; using less of it is the way out |
|
|
202
|
+
|
|
203
|
+
The thresholds are the criteria already in the tool — the minimum size for a shared chunk to be a
|
|
204
|
+
signal, and the number of importers above which a package counts as infrastructure — so the tag moves
|
|
205
|
+
when the reader moves them.
|
|
206
|
+
|
|
207
|
+
**The tags describe the measurement, they do not rate the work.** An earlier version said "not worth
|
|
208
|
+
it" and "no easy fix": both are claims about somebody else's project, and a reader who knows better
|
|
209
|
+
can simply be right. "No dominant source" is a statement about the import graph, which the reader can
|
|
210
|
+
open and check. The cost figure ranks, the tag says where to look, the conclusion stays with whoever
|
|
211
|
+
draws it.
|
|
212
|
+
|
|
213
|
+
The tab totals them at the top: of the chunks almost everybody downloads, how many have a named
|
|
214
|
+
source and how much of a typical visit they account for.
|
|
215
|
+
|
|
216
|
+
### 2.8 The shape of the split
|
|
217
|
+
|
|
218
|
+
Every other figure judges one thing — this chunk, that screen, this package. After a list of a hundred
|
|
219
|
+
chunks, the question none of them answers is whether the build is **well divided**.
|
|
220
|
+
|
|
221
|
+
That is not a property of any row. More chunks is not better and fewer is not better: what matters is
|
|
222
|
+
that what a screen needs at once arrives in few pieces and what it may never need stays apart. So it
|
|
223
|
+
is measured on the distribution (`core/analysis/shape.ts`), with two numbers per zone:
|
|
224
|
+
|
|
225
|
+
- **Concentration**: how much of a zone sits in its largest chunk. Fifteen shared chunks where one
|
|
226
|
+
holds 93 % is a different situation from fifteen even ones, and a list of fifteen rows hides it.
|
|
227
|
+
- **Crumbs**: how many pieces are under 5 kB, and what they add up to. One crumb is fine; many
|
|
228
|
+
arriving together is a split that went further than it helps.
|
|
229
|
+
|
|
230
|
+
The same reading applies to a single download (`granularityOf`), which is what a screen's detail says:
|
|
231
|
+
"29 files, and 4 of them are 80 % of the weight. 19 are under 5 kB."
|
|
232
|
+
|
|
233
|
+
⚠️ **It never says a number of chunks is wrong.** A small chunk that is genuinely lazy is doing its
|
|
234
|
+
job (§3.14), so the block is descriptive on purpose: a few lines of fact above the list.
|
|
235
|
+
|
|
236
|
+
**How the block is ordered.** Two questions, nested: **when** each part comes down — eager or lazy,
|
|
237
|
+
the split every bundler reports — and, inside the lazy half, **who pays** for it. The three zones were
|
|
238
|
+
there first and are strictly finer, but reading "how much of this app is deferred at all" meant adding
|
|
239
|
+
two of the three rows in your head. So lazy is a line of its own with shared and own hanging from it,
|
|
240
|
+
and a bar above them carries the same three colours with a gap where eager ends. The filter buttons
|
|
241
|
+
follow the same order. In the tree, a chunk holding at least a quarter of its zone carries that figure
|
|
242
|
+
on its row — zone and size were already there, and the division of one by the other is what says
|
|
243
|
+
whether a row is where the weight is.
|
|
244
|
+
|
|
245
|
+
### 2.9 When a chunk arrives, and in how many round trips
|
|
246
|
+
|
|
247
|
+
**Eager or lazy** falls straight out of §2.1 and is a second name for what the report calls the
|
|
248
|
+
bootstrap. It is shown anyway because "lazy" is the word people arrive with, and putting it next to
|
|
249
|
+
"19 screens load it" is what makes the contradiction land.
|
|
250
|
+
|
|
251
|
+
**Round trips** is the part no bundler reports. A browser does not know a chunk exists until it has
|
|
252
|
+
downloaded and parsed the one importing it, so entering a screen costs at least two sequential
|
|
253
|
+
requests — the screen's chunk, then the shared chunks it imports — and three if one of those imports
|
|
254
|
+
another. Breadth-first from the screen's entry chunk over static imports, stopping at the bootstrap
|
|
255
|
+
because that is already there:
|
|
256
|
+
|
|
257
|
+
```js
|
|
258
|
+
const trips = wavesFrom(outputs, [screen.chunk], boot);
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
The distance is the shortest one, because the browser asks for a chunk as soon as the first parent
|
|
262
|
+
mentioning it is parsed. The count is per screen: the same shared chunk can be the second trip for one
|
|
263
|
+
screen and the third for another. It matters because two screens of 240 kB are not the same screen —
|
|
264
|
+
one trip at 200 ms of latency is 200 ms, three is 600 ms, and a table of bytes shows them as
|
|
265
|
+
identical.
|
|
266
|
+
|
|
267
|
+
**The first load is a separate calculation.** For the bootstrap the graph is not enough: Angular writes
|
|
268
|
+
the entry script and a `modulepreload` link per initial chunk into `index.html`, and everything that
|
|
269
|
+
page names is requested at once regardless of its depth in the graph. A bootstrap chunk it does not
|
|
270
|
+
name is discovered by parsing, which is another trip. So the figure only exists when the build folder
|
|
271
|
+
was loaded with that page; without it, Loadline says "not known" rather than printing a number derived
|
|
272
|
+
from the wrong thing. The page is read with regular expressions rather than `DOMParser`, so the
|
|
273
|
+
command and the browser read it the same way.
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## 3. The signals
|
|
278
|
+
|
|
279
|
+
A number on its own is not a problem. What turns data into something worth touching is context: how
|
|
280
|
+
many people pay for it, who really uses it, and what fixing it costs.
|
|
281
|
+
|
|
282
|
+
### 3.1 Common code dressed as lazy
|
|
283
|
+
|
|
284
|
+
**Fires when** a chunk is imported by ≥ 60 % of screens and weighs more than 50 kB.
|
|
285
|
+
|
|
286
|
+
It is not lazy in any useful sense; it always downloads.
|
|
287
|
+
|
|
288
|
+
**What not to do**: split it on reflex. If most of the weight really is used by nearly every screen —
|
|
289
|
+
a table, form fields, the sidebar — splitting redistributes it rather than removing it. What pays off
|
|
290
|
+
is pulling out the components a **single** screen uses.
|
|
291
|
+
|
|
292
|
+
### 3.2 Bootstrap for a lazy screen
|
|
293
|
+
|
|
294
|
+
**Fires when** a package over 25 kB sits in the bootstrap, is imported by ≤ 4 files, **and at least
|
|
295
|
+
one of those files is a lazily loaded screen**.
|
|
296
|
+
|
|
297
|
+
⚠️ **That last condition is what makes the signal useful.** The obvious criterion — "few files import
|
|
298
|
+
it" — also flags your theme, which one file imports and which genuinely is needed before first paint.
|
|
299
|
+
What separates a real candidate is that its consumer lives in a lazy screen. The case that produced
|
|
300
|
+
it: a Microsoft sign-in library registered in the bootstrap config whose real consumer was the login
|
|
301
|
+
screen, downloaded by everyone including people who already had a session.
|
|
302
|
+
|
|
303
|
+
⚠️ **The label says "≤ 4 importers, at least one lazy", not "only lazy screens import it".** The
|
|
304
|
+
second is a stronger claim than the rule makes: a package with three bootstrap importers and one lazy
|
|
305
|
+
one matches too. The row carries the count (`2 of 3 in lazy screens: login, microsoft-callback`),
|
|
306
|
+
which is checkable and says which of the two cases the reader has.
|
|
307
|
+
|
|
308
|
+
**Where to touch**: the signal gives the import chain the package enters through and the routes file
|
|
309
|
+
that loads the screen. Both come from the metafile's `inputs` graph — the chain is the shortest path
|
|
310
|
+
over static imports from `main.ts` to the package (`main.ts › app.config.ts ›
|
|
311
|
+
core/config/msal.config.ts › @azure/msal-browser`), and the routes file is the one doing the
|
|
312
|
+
`import()` of the screen. The last file of yours in the chain holds the import to move; the routes
|
|
313
|
+
file is where the providers go.
|
|
314
|
+
|
|
315
|
+
### 3.3 Large source file
|
|
316
|
+
|
|
317
|
+
**Fires when** one of your own files exceeds 20 kB inside the bootstrap.
|
|
318
|
+
|
|
319
|
+
Usually a constants table — translation keys, catalogues, routes — pulled in whole because it is
|
|
320
|
+
referenced from everywhere. Check the compressed size before touching it: repetitive text compresses
|
|
321
|
+
enormously, and what looks like the second-biggest problem raw can be irrelevant.
|
|
322
|
+
|
|
323
|
+
### 3.4 Duplicate versions
|
|
324
|
+
|
|
325
|
+
**Fires when** the same package appears at two versions in the metafile paths.
|
|
326
|
+
|
|
327
|
+
You pay the weight twice because two dependencies ask for incompatible ranges. Knowing there are two
|
|
328
|
+
says nothing about what to do, so each copy is followed separately and reported with its import chain,
|
|
329
|
+
its size, whether it lands in the bootstrap and who imports it. With that, the fix is decided without
|
|
330
|
+
opening the lockfile: if both copies come in through dependencies you asked for, align the versions in
|
|
331
|
+
`package.json`; if one is dragged in by a dependency of a dependency, the resolution has to be forced.
|
|
332
|
+
In the application this was checked against, `@primeuix/utils` 0.7.2 came in through `primeng` and
|
|
333
|
+
0.6.4 through `@primeuix/styled`, neither asked for directly, so aligning `package.json` would have
|
|
334
|
+
moved nothing.
|
|
335
|
+
|
|
336
|
+
Only a copy that actually weighs something in some chunk counts: a version resolved but tree-shaken
|
|
337
|
+
away is not paid twice.
|
|
338
|
+
|
|
339
|
+
### 3.5 Expensive screen
|
|
340
|
+
|
|
341
|
+
**Fires when** a screen carries more than 6× the median of its own code, and over 100 kB.
|
|
342
|
+
|
|
343
|
+
It drags in a heavy library for itself alone. If that library is only needed once you open something
|
|
344
|
+
_inside_ the screen — a viewer, an editor, a chart — it belongs in a deferred block.
|
|
345
|
+
|
|
346
|
+
### 3.6 Against the previous measurement
|
|
347
|
+
|
|
348
|
+
These fire only with a baseline loaded: the previous build's `stats.json`, a Loadline export, or the
|
|
349
|
+
whole previous build folder. Both measurements are always compared in the same mode — a bare previous
|
|
350
|
+
`stats.json` is compared raw even if the report is compressed, and the table says so. For compressed
|
|
351
|
+
against compressed, give the previous folder with its `stats.json` inside.
|
|
352
|
+
|
|
353
|
+
- **The bootstrap has grown** — by 10 % and 10 kB or more, editable under Criteria.
|
|
354
|
+
- **A package has entered the bootstrap** — an npm package that was not in the baseline's. Project
|
|
355
|
+
folders do not count: they change with every commit.
|
|
356
|
+
- **A screen has grown** — shared + own is compared, **without the bootstrap**. Comparing totals, a
|
|
357
|
+
bigger bootstrap would flag all twenty screens at once.
|
|
358
|
+
|
|
359
|
+
⚠️ **One trap remains**: when a near-global shared chunk grows, every screen loading it goes up by the
|
|
360
|
+
same amount — in one real app, 19 screens at "+247 kB". So when most screens grow by about the same
|
|
361
|
+
amount, the signal changes: it says a shared chunk grew and sends you to that tab, not to 19 places.
|
|
362
|
+
|
|
363
|
+
### 3.7 The size budget that does not apply
|
|
364
|
+
|
|
365
|
+
These fire only with `angular.json` loaded; the pipeline ones also need `.gitlab-ci.yml` or the GitHub
|
|
366
|
+
workflow. With `package.json`, scripts are followed: `pnpm run build:pre` → `ng build
|
|
367
|
+
--configuration=preproduction`.
|
|
368
|
+
|
|
369
|
+
- **The strictest budget lives in a configuration the pipeline does not build.** Angular only checks
|
|
370
|
+
the `budgets` of the configuration it builds. This is the failure that motivated the tool: in one
|
|
371
|
+
app the 1.5 MB budget lived in `production` while the pipeline built `development` (no budget) and
|
|
372
|
+
`preproduction` (3 MB).
|
|
373
|
+
- **The budget cannot fire** — `maximumError` is more than twice the current raw bootstrap.
|
|
374
|
+
- **The budget only warns** — a `maximumWarning` with no `maximumError`. A warning in the build output
|
|
375
|
+
is read the first time and ignored the second.
|
|
376
|
+
- **No configuration declares a budget.**
|
|
377
|
+
|
|
378
|
+
Angular's budgets measure initial JS + CSS uncompressed; Loadline compares against the raw bootstrap
|
|
379
|
+
JS, and the difference is the few kB of `styles.css`.
|
|
380
|
+
|
|
381
|
+
### 3.8 No zone.js
|
|
382
|
+
|
|
383
|
+
Informational, not counted towards the verdict. Detected from the polyfills in `angular.json` or from
|
|
384
|
+
the absence of `zone.js` among the dependencies. It rules out the material about change detection
|
|
385
|
+
cycles, `NgZone` and `runOutsideAngular` up front: in a zoneless project there is nothing to optimise
|
|
386
|
+
there.
|
|
387
|
+
|
|
388
|
+
### 3.9 CommonJS package
|
|
389
|
+
|
|
390
|
+
**Fires when** a file under `node_modules` has `format: "cjs"` in the metafile. To review when the
|
|
391
|
+
package sits in the bootstrap, informational when only some screens load it.
|
|
392
|
+
|
|
393
|
+
A CommonJS package cannot be analysed at build time, so every file of it you import comes in whole
|
|
394
|
+
even for a single function. It is the same warning Angular prints ("CommonJS or AMD dependencies can
|
|
395
|
+
cause optimization bailouts"), with the size, the zone it lands in and who imports it — or which
|
|
396
|
+
package drags it in, when no file of yours imports it directly.
|
|
397
|
+
|
|
398
|
+
It comes from the metafile rather than the build output because esbuild records the format of every
|
|
399
|
+
file it processes: nothing to paste, no `package.json` under `node_modules` to read, and no false
|
|
400
|
+
positive from grepping `"type"` and hitting `"type": "git"`.
|
|
401
|
+
|
|
402
|
+
The size is raw and is what the file takes inside the chunk. Adding the package to
|
|
403
|
+
`allowedCommonJsDependencies` only silences the warning.
|
|
404
|
+
|
|
405
|
+
### 3.10 Against the browser's measurement
|
|
406
|
+
|
|
407
|
+
**Fires when** somebody pastes what their browser downloaded into the Measured tab. Three signals:
|
|
408
|
+
measured above computed, the router loading an area the guard then rejects, and measured below
|
|
409
|
+
computed (informational).
|
|
410
|
+
|
|
411
|
+
**What is compared** is the set of chunks, not the byte figure. A chunk that came down without being
|
|
412
|
+
predicted is a fact, whatever unit the report is in. Only afterwards is the difference priced with
|
|
413
|
+
Loadline's own figures.
|
|
414
|
+
|
|
415
|
+
**How it is attributed to a screen**: the one that best explains what came down — every chunk of its
|
|
416
|
+
own present counts, every one missing counts against — overridable by hand. If only the bootstrap came
|
|
417
|
+
down there is no screen, and that is the right answer.
|
|
418
|
+
|
|
419
|
+
**Where the guard signal comes from**: extra chunks exclusive to other screens. It is not "the
|
|
420
|
+
computation falls short", it is "this screen paid for that one". The fix is `canMatch` rather than
|
|
421
|
+
`canActivate`: the first discards the route without requesting its chunk, the second runs once it is
|
|
422
|
+
already down.
|
|
423
|
+
|
|
424
|
+
CSS, fonts and images are not counted — Loadline's figures are JavaScript. A downloaded `.js` that is
|
|
425
|
+
not from this build is shown separately: it almost always means a different deployment is being
|
|
426
|
+
measured.
|
|
427
|
+
|
|
428
|
+
### 3.11 Every language of a library
|
|
429
|
+
|
|
430
|
+
**Fires when** a package ships three or more distinct languages adding up to 10 kB or more. To review
|
|
431
|
+
in the bootstrap, informational otherwise.
|
|
432
|
+
|
|
433
|
+
A library that keeps its languages in a `locale/` folder ships all of them when imported from its
|
|
434
|
+
root, and then one gets used. It is the single largest cut reported in the field — one team went from
|
|
435
|
+
443 MB to 46 MB of build output by excluding locale files — and it hides well, because no individual
|
|
436
|
+
file is big.
|
|
437
|
+
|
|
438
|
+
**Why languages and not files**: `date-fns` splits one language across ten files under
|
|
439
|
+
`locale/en-US/_lib/`, so counting files would report ten languages where there is one. Distinct codes
|
|
440
|
+
are counted instead, looked for in the two places libraries put them: the file name
|
|
441
|
+
(`moment/locale/es.js`, `primelocale/es.json`) and the folder right after `locale/`
|
|
442
|
+
(`date-fns/locale/es/index.js`). There is no list of package names, because a list would be right for
|
|
443
|
+
the libraries in fashion today and wrong for next year's; the folder convention is older than any of
|
|
444
|
+
them.
|
|
445
|
+
|
|
446
|
+
### 3.12 Data travelling as code
|
|
447
|
+
|
|
448
|
+
**Fires when** `.json` files inside the bundle add up to 10 kB or more, once the ones already reported
|
|
449
|
+
as languages are taken out. To review in the bootstrap, informational otherwise.
|
|
450
|
+
|
|
451
|
+
An `import` of a data file is not a reference: the content ends up embedded in a chunk of JavaScript,
|
|
452
|
+
downloaded and parsed with it. A list of countries for a dropdown is the usual case. Fetched with a
|
|
453
|
+
request instead, it caches on its own, does not block startup, and changing it does not invalidate the
|
|
454
|
+
JavaScript.
|
|
455
|
+
|
|
456
|
+
### 3.13 Source maps in the folder you deploy
|
|
457
|
+
|
|
458
|
+
**Fires when** the build folder brings `.js.map` files. Informational always: Loadline cannot know
|
|
459
|
+
whether that folder is the one deployed, and says so instead of accusing.
|
|
460
|
+
|
|
461
|
+
A source map reconstructs your source from the compiled output. It does not weigh on the download —
|
|
462
|
+
the browser only asks for it if somebody opens the tools — but if those files reach the server,
|
|
463
|
+
whoever knows the URL has your code. `"sourceMap": { "scripts": true, "hidden": true }` generates them
|
|
464
|
+
without linking them from the bundle, which is what you want in order to upload them to an error
|
|
465
|
+
tracker; the part that gets forgotten is that not linking them is not the same as not serving them.
|
|
466
|
+
|
|
467
|
+
It is the one finding in the report that is not about size, and it costs nothing, since the folder is
|
|
468
|
+
already read for the compressed figures.
|
|
469
|
+
|
|
470
|
+
### 3.14 Many requests for one screen
|
|
471
|
+
|
|
472
|
+
**Fires when** the typical screen downloads more files than `screenFilesMax` (30 by default, editable)
|
|
473
|
+
**and** at least five of them are under 1 kB. To review.
|
|
474
|
+
|
|
475
|
+
The one figure in the report that is not about bytes. Each file is a request, a cache entry and a
|
|
476
|
+
module wrapper; below a kilobyte, asking for it costs about what it holds.
|
|
477
|
+
|
|
478
|
+
**Why two conditions**: a file count on its own says "your application is large", which is not a
|
|
479
|
+
finding. The two together say "this is split further than it helps", which is.
|
|
480
|
+
|
|
481
|
+
**Why what a screen loads and not the build's chunk list**: a small chunk is not a problem when it is
|
|
482
|
+
genuinely lazy. A 5 kB chunk for an admin screen hardly anybody opens is doing its job — those 5 kB
|
|
483
|
+
never download. Only code that arrives **together** counts, so the signal looks at the bootstrap plus
|
|
484
|
+
what that one screen pulls in.
|
|
485
|
+
|
|
486
|
+
**What it does not claim**: that chunks under 30 kB are bad, which is the shape this rule usually
|
|
487
|
+
takes and is wrong; or that more requests are worse, which over HTTP/2 and HTTP/3 they are not.
|
|
488
|
+
|
|
489
|
+
**What to do**: the split is nobody's decision. The bundler makes one chunk per distinct set of
|
|
490
|
+
screens reaching a module, so many chunks means many combinations. They come down by removing
|
|
491
|
+
combinations — a barrel file imported by a handful of screens produces one chunk per mix — and merging
|
|
492
|
+
by hand (`manualChunks`, `ngx-build`) can make caching worse.
|
|
493
|
+
|
|
494
|
+
### 3.15 Your own code in the bootstrap for a deferred screen
|
|
495
|
+
|
|
496
|
+
**Fires when** folders of your own code in the bootstrap, whose files are imported by at least one
|
|
497
|
+
deferred screen and held there by no more than four files that are not screens, add up to half of what
|
|
498
|
+
a package has to weigh to be named. To review.
|
|
499
|
+
|
|
500
|
+
The same question §3.2 asks of an npm package, asked of your code: a service imported by
|
|
501
|
+
`app.config.ts` and by one page downloads on every visit, while the page it was written for is
|
|
502
|
+
deferred.
|
|
503
|
+
|
|
504
|
+
**Why by folder and not by file.** Written per file first, it found nothing on a real build: the
|
|
505
|
+
business layer was in the bootstrap across thirty files of one to three kilobytes each, every one far
|
|
506
|
+
below any size worth naming and together a layer that should not be there. The folder is the unit the
|
|
507
|
+
problem has. The size floor applies to the **total** for the same reason one level up — one folder of
|
|
508
|
+
two kilobytes is noise, the same layer across six of them is a pattern — while the structural
|
|
509
|
+
condition is checked per folder.
|
|
510
|
+
|
|
511
|
+
**What it insists on**: the list of files keeping it in the bootstrap, all of them. Moving the first
|
|
512
|
+
and leaving the other two changes nothing, which is the mistake the signal exists to prevent. If the
|
|
513
|
+
bootstrap file that imports it genuinely needs it, there is nothing to move and the signal is a fact
|
|
514
|
+
rather than a task, which the text says.
|
|
515
|
+
|
|
516
|
+
### 3.16 The first load in several round trips
|
|
517
|
+
|
|
518
|
+
**Fires when** `index.html` was read and does not name every chunk of the bootstrap, so the browser
|
|
519
|
+
only discovers one of them after parsing another. To review.
|
|
520
|
+
|
|
521
|
+
What §3.5 says about a screen, said about the one load nobody skips. A chunk the page names — the
|
|
522
|
+
entry script or a `modulepreload` link — is requested straight away; one it does not name waits for
|
|
523
|
+
the chunk importing it to arrive and be parsed. Same bytes, one round trip later, in front of the
|
|
524
|
+
first paint.
|
|
525
|
+
|
|
526
|
+
**Why it has no threshold**, while everything else weighs something against a criterion: "how many
|
|
527
|
+
files is too many" is a judgement and this is not one. Either the page names the whole bootstrap or it
|
|
528
|
+
does not.
|
|
529
|
+
|
|
530
|
+
**What to do**: a `modulepreload` link for the missing chunks. Angular emits them for the initial
|
|
531
|
+
chunks and Vite has `build.modulePreload`; when that is switched off, this is the bill. If those
|
|
532
|
+
chunks turn out not to be needed before the first paint, deferring them is the better fix, because
|
|
533
|
+
then the first load also weighs less.
|
|
534
|
+
|
|
535
|
+
### 3.17 A folder without source maps
|
|
536
|
+
|
|
537
|
+
**Fires when** the graph was read from the folder and the folder carries no `.js.map`. Informational
|
|
538
|
+
always: not a problem with the build, a shorter report.
|
|
539
|
+
|
|
540
|
+
The weight of each chunk is known and what is inside it is not. Screens end up named after their chunk
|
|
541
|
+
file — `0fPdmq0U.js` rather than `orders` — and there is no breakdown by package and no chain from the
|
|
542
|
+
entry point. Everything else comes out in full. It exists because two real builds, elk and immich,
|
|
543
|
+
neither of which publishes maps, came out as a page of hashes with nothing to explain them.
|
|
544
|
+
|
|
545
|
+
### 3.18 What the report cannot reach
|
|
546
|
+
|
|
547
|
+
**Fires when** some JavaScript of the build is imported by nothing reachable from the entry point, by
|
|
548
|
+
either kind of import. A problem when those chunks are most of the bytes, informational otherwise.
|
|
549
|
+
|
|
550
|
+
The only signal about the report rather than about the build. Three things land here, with a different
|
|
551
|
+
answer each: a **service worker**, which is not part of any load a browser makes from the page; an
|
|
552
|
+
`import()` whose **path is built at run time**, which VitePress writes one of per page; and the
|
|
553
|
+
**leftovers of a previous build** in a folder nobody empties.
|
|
554
|
+
|
|
555
|
+
**Why the share decides the severity**: the Vue documentation site has 244 chunks and 233 of them —
|
|
556
|
+
9.2 MB — are page chunks reached that way. Describing the other eleven and saying nothing about those
|
|
557
|
+
is the report describing a corner of the build in the voice it uses for the whole of it. Two service
|
|
558
|
+
workers in a 45 MB folder are a footnote, and printing both the same way would bury the first.
|
|
559
|
+
|
|
560
|
+
### 3.19 The hash cascade
|
|
561
|
+
|
|
562
|
+
**Fires when** a chunk carries the hashed names of two or more others inside it, which is nearly
|
|
563
|
+
always. Informational by default — see §3.22 for what gives it a colour.
|
|
564
|
+
|
|
565
|
+
A bundler writes the hashed file name of every chunk it imports **into** the chunk importing it. So
|
|
566
|
+
changing a leaf changes the leaf's hash, which changes the text of whatever names it, which changes
|
|
567
|
+
that file's hash, and so on. The mental model to correct is that this travels upwards: the usual shape
|
|
568
|
+
in Vite and Rollup is **hub-and-spoke**, one shared chunk every route imports and that transitively
|
|
569
|
+
reaches them all. Change a leaf → the hub changes → everything importing the hub changes, which in a
|
|
570
|
+
single-page application is nearly everything. It does not grow with depth; it jumps.
|
|
571
|
+
|
|
572
|
+
**Measured rather than argued about.** The topology says how far a change travels, so it is read off
|
|
573
|
+
this build — which chunk names the most others, and how many name it — and reported as LOW, MID or
|
|
574
|
+
HIGH with the reason. LOW is the runtime-chunk shape, which is what webpack emits and what largely
|
|
575
|
+
avoids the problem, with the caveat that usually gets dropped: that chunk changes on every deploy and
|
|
576
|
+
has to be tiny and inlined, or the cost comes straight back.
|
|
577
|
+
|
|
578
|
+
**With a baseline it stops being a model.** Two builds diffed by file name _are_ the delta a browser
|
|
579
|
+
would pay. The changed files split into the ones where the edit landed and the ones that only moved
|
|
580
|
+
because a name inside them moved; the second group is the cascade, with its counterfactual next to it.
|
|
581
|
+
|
|
582
|
+
**Where there is no edit left to point at.** `roots` is the changed files that name no other changed
|
|
583
|
+
file. On the default Vite and Rollup layout there are none — the lazy chunks import back from the
|
|
584
|
+
entry chunk, so the naming graph among the changed files closes on itself — and eight of the nineteen
|
|
585
|
+
framework probes came out that way. The sentence read _"only 0 name no other file that also changed
|
|
586
|
+
(0 B): ."_, followed by "that is where the edit landed" and a counterfactual saying the deploy would
|
|
587
|
+
have cost nothing. All three false. It now says the split is unavailable and why, which is itself the
|
|
588
|
+
finding: a naming graph that closes on itself **is** the hub shape, and the case where the cascade
|
|
589
|
+
argument is strongest.
|
|
590
|
+
|
|
591
|
+
**Except where the name _is_ the hash.** SvelteKit, Nuxt and Rollup write chunks called `ChDGvcpR.js`,
|
|
592
|
+
and taking the hash off one of those leaves `.js`. Matching by name had nothing to work with, so every
|
|
593
|
+
chunk read as one file gone and another arrived: on the Nuxt probe, a one-line edit to a shared module
|
|
594
|
+
came out as **8 files removed and 8 added, 100 % of the build re-downloaded, and an empty
|
|
595
|
+
edit-versus-cascade split**. Those chunks are matched instead by the largest source file inside them,
|
|
596
|
+
which the analysis already works out — not a heuristic over the bytes, but what the chunk is made of,
|
|
597
|
+
read from the same metafile or source map the weights come from. A content key naming two chunks on
|
|
598
|
+
one side is not used, and where the build said nothing about its contents, matching falls back to the
|
|
599
|
+
name. The same edit now reads: **4 files changed, 94 %, and 339 B of it is the edit.**
|
|
600
|
+
|
|
601
|
+
**What not to do**: reach for coarser chunks. The two arguments point in opposite directions —
|
|
602
|
+
compression dictionaries make the re-download cheap rather than rarer, and a bigger chunk invalidates
|
|
603
|
+
more — so every way out is named with its price and none is recommended. Import maps move the
|
|
604
|
+
specifiers into the HTML, at the cost of an uncacheable HTML, which it usually already is. Breaking
|
|
605
|
+
the hub with `manualChunks` is paid for with a bigger first load, which Rollup's own documentation
|
|
606
|
+
says.
|
|
607
|
+
|
|
608
|
+
⚠️ **A citation worth reading in full**: tooling.report's tests say Rollup should not have this
|
|
609
|
+
problem, and they cover a two-level case. A real application with one shared chunk every route imports
|
|
610
|
+
fails all the same. The citation is correct and does not mean what it looks like.
|
|
611
|
+
|
|
612
|
+
### 3.20 What is served, rather than what was built
|
|
613
|
+
|
|
614
|
+
**Fires when** somebody pastes the browser measurement, which is the only source for anything in this
|
|
615
|
+
section.
|
|
616
|
+
|
|
617
|
+
Half the report reasons about round trips, compression and caching from the folder alone, which is
|
|
618
|
+
reasoning about what was _built_. A `.br` next to a `.js` says the pipeline made one; only
|
|
619
|
+
`encodedBodySize` against `decodedBodySize` says the server sent it. A hashed name says the file _can_
|
|
620
|
+
be cached forever; only a `transferSize` of zero says a returning visitor did not ask again.
|
|
621
|
+
|
|
622
|
+
| What it reads | What it tells you that the folder cannot |
|
|
623
|
+
| ------------------------------------- | ------------------------------------------------------------------------- |
|
|
624
|
+
| `encoded` vs `decoded` body size | JavaScript being served uncompressed. Worth more than any chunk split |
|
|
625
|
+
| `transferSize` of 0, or a few hundred | Served from cache, or a 304 — the premise §3.19 assumed |
|
|
626
|
+
| `connectStart` on the n-th file | The HTTP/1.1 pool running out, observed rather than inferred |
|
|
627
|
+
| `responseStart − requestStart` | A real round trip, better than asking somebody about their latency |
|
|
628
|
+
| `responseStart` of the navigation | The document's own TTFB: round trip zero, which the count starts after |
|
|
629
|
+
| Every request, third parties too | The denominator a count of JavaScript files never had |
|
|
630
|
+
| `serviceWorker.controller` | A worker **controlling** this page, not just present in the folder |
|
|
631
|
+
| `startTime`, sorted | The batches the browser really took, against the ones the graph predicted |
|
|
632
|
+
|
|
633
|
+
That last row needs both halves: the vendors with the waterfall have no module graph, the analysers
|
|
634
|
+
with the graph have no waterfall. Loadline can say "the graph predicted 3 round trips, you measured
|
|
635
|
+
4" — with the correction made while building it, that a measured batch is **not** a round trip of the
|
|
636
|
+
graph, because a batch also splits when the connection pool runs out. The copy says so and names the
|
|
637
|
+
queueing when there is any.
|
|
638
|
+
|
|
639
|
+
**None of it moves a threshold.** One paste describes one machine, on one connection, on one day. An
|
|
640
|
+
`h3` measured from a laptop on office fibre is a fact about that laptop: a new visitor's first
|
|
641
|
+
connection is usually `h2`, because `Alt-Svc` has to be cached first, and a corporate proxy that drops
|
|
642
|
+
UDP degrades it for a whole company. So the channel is reported with its date and its limits attached,
|
|
643
|
+
it goes stale after thirty days, and it is never written into the committed file.
|
|
644
|
+
|
|
645
|
+
### 3.21 Where the first load comes from
|
|
646
|
+
|
|
647
|
+
**Fires when** `index.html` names an absolute URL on another host, or the measurement reports one.
|
|
648
|
+
|
|
649
|
+
Before the first byte of the first chunk there is a DNS lookup, a TCP connection and a TLS handshake
|
|
650
|
+
against that host — time no weight figure in this report sees, because the round-trip count starts
|
|
651
|
+
once the connection exists. It has an opposite side, said in the same sentence: under HTTP/1.1 a
|
|
652
|
+
second origin is a second pool of six, so the decision that adds a handshake also removes queueing.
|
|
653
|
+
|
|
654
|
+
Both sources are read because a page written entirely with relative URLs and served from a CDN names
|
|
655
|
+
no other host in its markup; only the addresses the browser reported say where the bytes came from,
|
|
656
|
+
which makes the measured version the stronger of the two.
|
|
657
|
+
|
|
658
|
+
### 3.22 The five questions
|
|
659
|
+
|
|
660
|
+
**Fires when** somebody answers them, or — for the card listing what is still open — when a signal on
|
|
661
|
+
this report depends on an answer nobody has given.
|
|
662
|
+
|
|
663
|
+
Four claims in this report are grey on purpose: the update cost shows its percentage and withholds its
|
|
664
|
+
colour, the cascade names its topology and refuses to say whether it matters, and the granularity
|
|
665
|
+
signal puts two magnitudes on the table and declines to recommend a direction. The facts that would
|
|
666
|
+
settle them are facts about a team and its users, and no folder on disk contains them.
|
|
667
|
+
|
|
668
|
+
**The arithmetic**: `releases per week × the share arriving with a warm cache` = how many times a week
|
|
669
|
+
one person pays an invalidation. The report shows the multiplication rather than the result, so anyone
|
|
670
|
+
who disagrees can see which of the two numbers they disagree with. It is what turns "87 % of the build
|
|
671
|
+
is re-downloaded" into a cost: 87 % four times a week is the most expensive line in the report; 87 %
|
|
672
|
+
once a quarter to first-time visitors is nothing at all. Same build, same percentage.
|
|
673
|
+
|
|
674
|
+
**The rule, which is half the work**: an answer may **raise** a severity and may never lower one, and
|
|
675
|
+
`unknown` does nothing at all. A test walks all 768 combinations of the five answers against a build
|
|
676
|
+
with an expensive update and asserts that none takes a signal below where nobody having answered
|
|
677
|
+
leaves it, and that none makes a signal disappear. Without that guard, the cheapest way to a clean
|
|
678
|
+
report would be to answer optimistically, and the questionnaire would stop being evidence and become a
|
|
679
|
+
volume knob.
|
|
680
|
+
|
|
681
|
+
**Why the questions are words and the figures optional**: people know "we ship most days"; almost
|
|
682
|
+
nobody knows their releases per week without looking it up. Asking for the figure first produces
|
|
683
|
+
either an empty form or a guess typed with two decimal places, and the guess is worse, because it
|
|
684
|
+
arrives looking like a measurement. So the bands are the question, with three raw controls beside them
|
|
685
|
+
for whoever has the query open in another window; when a figure is there, it wins. Under every question
|
|
686
|
+
is the metric it stands for and where to find it, which is what keeps this from being a personality
|
|
687
|
+
quiz.
|
|
688
|
+
|
|
689
|
+
**Two questions are not like the others.** The fourth — where the audience connects from — is the one
|
|
690
|
+
people answer as they would like it to be, and it says so; ticking "we have RUM" removes it entirely,
|
|
691
|
+
because a p75 measured from real sessions beats a band picked from memory. It is also the only one
|
|
692
|
+
with no raw control of its own: its unit is round-trip time, the report already has exactly one of
|
|
693
|
+
those (`latencyMs`), and a second copy would be two numbers for one fact drifting apart. The fifth
|
|
694
|
+
offers no "I don't know" at all: it is not a fact to look up but which wait the team would rather pay.
|
|
695
|
+
It is also the only place the report names a **direction**, because it is the only place anything
|
|
696
|
+
ranks the two magnitudes.
|
|
697
|
+
|
|
698
|
+
**Only the questions that matter are asked.** The card listing what is still open names only the
|
|
699
|
+
questions some signal on this report depends on. Otherwise it would be five identical lines on every
|
|
700
|
+
report, which is the shape of text people learn to scroll past.
|
|
701
|
+
|
|
702
|
+
**"I don't know" is never drawn as a chosen answer.** `unknown` is the starting value of all five, so
|
|
703
|
+
a form nobody had touched came up with "I don't know" selected on every question, beside a counter
|
|
704
|
+
saying "unanswered". Both could not be true. No line of code downstream tells "nobody looked" from
|
|
705
|
+
"somebody said they do not know" — neither counts as answered, neither moves a colour — so the page
|
|
706
|
+
must not show them differently either. The button stays, as the way to take an answer back.
|
|
707
|
+
|
|
708
|
+
### 3.23 The breakdown that does not add up to the file
|
|
709
|
+
|
|
710
|
+
**Fires when** the per-file weights inside the chunks and the chunks' own weights disagree by more
|
|
711
|
+
than 5 % **and** by more than a kibibyte per chunk. `mid` from 15 % up, informational below it.
|
|
712
|
+
|
|
713
|
+
Both conditions, because they measure different things. The wrapper a bundler puts round each chunk —
|
|
714
|
+
module boilerplate, banners, the `sourceMappingURL` line — belongs to no input file and is a fixed cost
|
|
715
|
+
per chunk rather than a proportion of one. A plain esbuild build of five chunks weighing 90 to 330
|
|
716
|
+
bytes each comes out at **59 %**, which is 395 bytes of wrapper and nothing else; without the second
|
|
717
|
+
condition that was a `mid` on a build where nothing was wrong. The ratio says whether it matters, the
|
|
718
|
+
bytes say whether it is real.
|
|
719
|
+
|
|
720
|
+
There are two measurements of the same chunk and they are supposed to agree: `bytes` is what the file
|
|
721
|
+
weighs, and the sum of `bytesInOutput` over its inputs is what it is made of. Every figure taken from
|
|
722
|
+
**inside** a chunk — the bootstrap broken down by package, the exclusive column, what a `--what-if`
|
|
723
|
+
would save — is a sum of the second kind, while the headline weight printed next to it is the first.
|
|
724
|
+
When the two disagree, the whole of the first family is wrong by exactly that ratio and nothing else
|
|
725
|
+
in the report shows it.
|
|
726
|
+
|
|
727
|
+
Measured on four builds:
|
|
728
|
+
|
|
729
|
+
| Build | chunk bytes | sum of `bytesInOutput` | ratio |
|
|
730
|
+
| --------------------------------- | ----------- | ---------------------- | ---------- |
|
|
731
|
+
| Angular 17 (probe) | 230 774 | 228 020 | **0.988** |
|
|
732
|
+
| Angular 22 (probe) | 225 684 | 283 571 | **1.256** |
|
|
733
|
+
| Angular 22 (a real application) | 393 504 | 483 159 | **1.228** |
|
|
734
|
+
| Angular 22 (Loadline's own build) | 791 012 | 790 569 | **0.9994** |
|
|
735
|
+
|
|
736
|
+
**The cause is not established, and the signal does not claim one.** The obvious reading — "Angular 22
|
|
737
|
+
writes the metafile before a later pass shrinks the output" — is contradicted by the fourth row, which
|
|
738
|
+
is Angular 22 on the same `@angular/build` 22.1.7 as the second and lands on the file exactly. What
|
|
739
|
+
separates them is not the version: the two that drift are chunks that are almost entirely `@angular/*`
|
|
740
|
+
framework code, and the one that does not is mostly this project's own. Extracted licences were
|
|
741
|
+
checked and are not it — the probe's excess is 57 887 bytes against a 16 954-byte
|
|
742
|
+
`3rdpartylicenses.txt`.
|
|
743
|
+
|
|
744
|
+
What **is** ruled out is esbuild itself. A plain esbuild build — no Angular, 40 modules, one 46 kB
|
|
745
|
+
shared chunk, `metafile: true`, `minify: true` — comes out at **0.9892**, and its biggest chunk at
|
|
746
|
+
**0.9975**: the deficit is the per-chunk wrapper, in the direction the overhead predicts. Whatever
|
|
747
|
+
moves the figure sits between esbuild's metafile and the folder Angular writes, on some of its builds.
|
|
748
|
+
|
|
749
|
+
**Why it is a signal and not a correction.** Scaling the breakdown down by the ratio would make the
|
|
750
|
+
totals reconcile and would be a model: it assumes every file moved by the same proportion, and nothing
|
|
751
|
+
here measures whether it did. There is an exact answer available instead, and the signal's fix is to
|
|
752
|
+
go and get it — build with source maps and drop the folder, and the split is measured on the generated
|
|
753
|
+
file itself. On the same Angular 22 probe, the graph walk over the metafile alone totals 280 153 bytes
|
|
754
|
+
against a 222 555-byte bootstrap (**+26 %**); with the maps alongside it, 221 555 (**−0.45 %**). It
|
|
755
|
+
does not fire on chunks a map covered, because for those there is nothing left to drift.
|
|
756
|
+
|
|
757
|
+
---
|
|
758
|
+
|
|
759
|
+
## 4. Traps found while building it
|
|
760
|
+
|
|
761
|
+
### 4.1 Computed is not measured
|
|
762
|
+
|
|
763
|
+
Loadline walks the graph; the browser measures. They do not match, and in a real case the gap was:
|
|
764
|
+
|
|
765
|
+
```
|
|
766
|
+
computed from the graph : 2389 kB across 21 files
|
|
767
|
+
measured in the browser : 2534 kB across 66 files
|
|
768
|
+
```
|
|
769
|
+
|
|
770
|
+
That is not a computation bug. Entering at the root, Angular's router loads the protected zone's chunk
|
|
771
|
+
in order to match the route, and only then does the guard find there is no session and redirect to
|
|
772
|
+
login — the chunk has already downloaded. So **opening the app at `/` costs more than going straight
|
|
773
|
+
to `/login`**. Both numbers are true and they answer different questions. The Measured tab (§3.10)
|
|
774
|
+
contrasts the two chunk by chunk, and what is left over is exactly the chunk the router loaded before
|
|
775
|
+
the guard did its job.
|
|
776
|
+
|
|
777
|
+
### 4.2 A static server does not know your routes
|
|
778
|
+
|
|
779
|
+
When verifying in the browser, `/login` returns 404 — the server is looking for a file. Enter at the
|
|
780
|
+
root and let the app redirect, or serve with a rewrite:
|
|
781
|
+
|
|
782
|
+
```bash
|
|
783
|
+
npx http-server dist/<app>/browser -p 8099 --proxy "http://localhost:8099?"
|
|
784
|
+
```
|
|
785
|
+
|
|
786
|
+
### 4.3 Analysis tools cache
|
|
787
|
+
|
|
788
|
+
At least one well-known analyser keeps the last report in browser storage and serves stale data
|
|
789
|
+
without saying so. Compare the `main-*.js` name it shows against the one on disk.
|
|
790
|
+
|
|
791
|
+
### 4.4 Nesting a route changes what guards see
|
|
792
|
+
|
|
793
|
+
Not Loadline's problem, but it is the trap in the fix Loadline recommends. Move a route under a parent
|
|
794
|
+
so you can declare lazily-loaded providers, and a guard that decides like this:
|
|
795
|
+
|
|
796
|
+
```ts
|
|
797
|
+
const url = (route.routeConfig?.path ?? '').toLowerCase();
|
|
798
|
+
```
|
|
799
|
+
|
|
800
|
+
…now sees a child with `path: ''`, stops recognising the route as public, and **redirects in a loop,
|
|
801
|
+
with the screen hung and no console error**. The fix: `title` and `canActivate` stay on the parent,
|
|
802
|
+
which keeps its `path`; only `providers` and `loadComponent` move down to the child.
|
|
803
|
+
|
|
804
|
+
---
|
|
805
|
+
|
|
806
|
+
## 5. Data format
|
|
807
|
+
|
|
808
|
+
Loadline reads the [esbuild metafile](https://esbuild.github.io/api/#metafile), written by Angular
|
|
809
|
+
with `--stats-json` and by plain esbuild with its metafile option. The keys it uses:
|
|
810
|
+
|
|
811
|
+
| Key | What for |
|
|
812
|
+
| ---------------------------------- | --------------------------------------------------------------------------------- |
|
|
813
|
+
| `outputs[].entryPoint` | Detecting entries and naming screens |
|
|
814
|
+
| `outputs[].imports[].kind` | `import-statement` vs `dynamic-import`: the entire split |
|
|
815
|
+
| `outputs[].bytes` | Raw chunk size |
|
|
816
|
+
| `outputs[].inputs[].bytesInOutput` | Breakdown by package and by folder, and the search |
|
|
817
|
+
| `inputs[].imports[]` | Who imports what: the import chain, §3.2, and which routes file loads each screen |
|
|
818
|
+
| `inputs[].format` | `cjs` marks CommonJS files, for §3.9 |
|
|
819
|
+
|
|
820
|
+
### The build folder, when there is no metafile
|
|
821
|
+
|
|
822
|
+
Vite, Rollup and Rolldown do not write a metafile, and Vite never compiled for production with esbuild
|
|
823
|
+
— it used Rollup, and since Vite 8 it uses Rolldown. So for everything built on them the graph is read
|
|
824
|
+
from the compiled folder itself (`core/intake/bundle-graph.ts`), which is possible because an ES
|
|
825
|
+
module bundle carries its graph in the code that ships:
|
|
826
|
+
|
|
827
|
+
| What is in the folder | What it gives |
|
|
828
|
+
| ------------------------------ | ------------------------------------------------------ |
|
|
829
|
+
| `import{a}from"./chunk-X.js"` | A static edge: the two files travel together |
|
|
830
|
+
| `import("./chunk-Y.js")` | A lazy edge: the boundary the whole report is built on |
|
|
831
|
+
| The `<script>` of `index.html` | Which chunk the application starts at |
|
|
832
|
+
| `__vitePreload(…, [deps])` | What Vite fetches in parallel with a lazy chunk |
|
|
833
|
+
| `.js.map` | Which source files are inside each chunk, and how much |
|
|
834
|
+
|
|
835
|
+
- **No JavaScript parser.** Specifiers are found with regular expressions and a match is kept only if
|
|
836
|
+
the file it points at exists in the folder, so a false positive points at nothing and drops out.
|
|
837
|
+
- **The page is required.** A bundler writes the shared code of an application into its entry chunk,
|
|
838
|
+
so the entry ends up imported by its own children: there is no "chunk nobody imports" to find. Only
|
|
839
|
+
`index.html` can name it. It does so in one of two ways — a `<script src>`, or an `import()` inside
|
|
840
|
+
an inline script, which is how SvelteKit starts its application.
|
|
841
|
+
- **A folder of webpack or Turbopack chunks is refused.** Those builds have entry chunks and no graph:
|
|
842
|
+
their imports are numbers the loader resolves at run time. Read as ES modules, a Next.js export came
|
|
843
|
+
out as one bootstrap of seven files, zero screens and "nothing stands out" — confident, detailed and
|
|
844
|
+
false. A folder whose entry carries that runtime **and** where nothing imports anything lazily is
|
|
845
|
+
named for what it is. Both halves are needed: the marker alone would refuse an ES bundle carrying
|
|
846
|
+
one webpack-built dependency, and no lazy edges alone is an ordinary application with every route
|
|
847
|
+
eager.
|
|
848
|
+
- **Without `.js.map` the report loses the inside of each chunk**, and nothing else.
|
|
849
|
+
|
|
850
|
+
The preload lists are the one place a bundler's own behaviour changes a figure. Vite does not wait for
|
|
851
|
+
a lazy chunk to arrive and be parsed before fetching what it imports — it bakes the list into the call
|
|
852
|
+
and asks for the whole set at once. Angular does not. Without reading those lists, every screen of a
|
|
853
|
+
Vite application would be counted one round trip deeper than it is.
|
|
854
|
+
|
|
855
|
+
### What is not a metafile
|
|
856
|
+
|
|
857
|
+
Three files are commonly believed to be "the stats of my build". "Could not read it" would be a lie
|
|
858
|
+
about all three: the file is fine, it is another format, and Loadline says which.
|
|
859
|
+
|
|
860
|
+
| What | Where it comes from | Why it is not read |
|
|
861
|
+
| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
|
|
862
|
+
| webpack `stats.json` | Angular's `browser` builder (up to v16), Next.js, Rspack | Different shape: `chunks`/`modules`/`assets` arrays |
|
|
863
|
+
| Vite `manifest.json` | `build.manifest: true` | Not needed: the folder itself says the same thing, and better |
|
|
864
|
+
| `rollup-plugin-visualizer` | its `--json` output | A drawn tree, not the build's own record |
|
|
865
|
+
|
|
866
|
+
The Vite manifest was the obvious thing to read and it aged badly in a few months: with Rolldown as
|
|
867
|
+
the default it is a compatibility layer somebody has to switch on, while the folder is always there
|
|
868
|
+
and needs nobody to maintain a format.
|
|
869
|
+
|
|
870
|
+
### Two build shapes that are not a plain SPA
|
|
871
|
+
|
|
872
|
+
Both were analysed wrongly at first, and both are becoming more common (`core/analysis/entries.ts`).
|
|
873
|
+
|
|
874
|
+
**Server-side rendering writes one metafile with both sides in it.** Nobody downloads the server
|
|
875
|
+
bundle and it is usually the bigger of the two, so "the entry that reaches the most" would pick it and
|
|
876
|
+
the whole report would be about code no browser asks for. Everything under `server/` is left out —
|
|
877
|
+
unless there is nothing else, which is somebody analysing their server bundle on purpose — and the
|
|
878
|
+
report says how many outputs that was.
|
|
879
|
+
|
|
880
|
+
**A deferred block looks exactly like a route from the outside.** An Angular `@defer` or a `lazy()`
|
|
881
|
+
inside a component produces a lazy entry with an `entryPoint` of your own code, same as a route's. It
|
|
882
|
+
is not a screen: nobody enters it, it loads when its trigger fires inside the screen holding it, and
|
|
883
|
+
counting it as one inflates the screen count and drags the median down. The evidence has to be
|
|
884
|
+
positive: it is a block only when **every** file that lazily imports it is a view (`*.component.*`,
|
|
885
|
+
`*.page.*`, `*.view.*`, `*.container.*`) or is itself one of these lazy entries. A route file, a
|
|
886
|
+
service, an unknown importer: it stays a screen.
|
|
887
|
+
|
|
888
|
+
**A file that only groups routes is not a screen either.** What it holds is a list of
|
|
889
|
+
somewhere-elses. This is measured rather than read off the file name: it is a grouping file when it
|
|
890
|
+
adds under a kibibyte of its own to its chunk, holds **more than one** dynamic import and nothing
|
|
891
|
+
else, and produces a chunk nothing travels with. `*.routes.ts` still passes on the name alone, for the
|
|
892
|
+
routes file that imports a guard, but nothing depends on that name any more.
|
|
893
|
+
|
|
894
|
+
⚠️ **"More than one" is the condition a real build had to teach.** A Nuxt page that defers a single
|
|
895
|
+
widget matched every other criterion — small, no static imports, a chunk of its own — so the home
|
|
896
|
+
screen left the table and the widget took its row. With a single dynamic import there is nothing left
|
|
897
|
+
that tells a grouping file from a small screen deferring a piece of itself, and losing a screen is the
|
|
898
|
+
expensive direction to be wrong in.
|
|
899
|
+
|
|
900
|
+
Both lists sit under the screens table, so leaving an entry out is visible rather than silent. Every
|
|
901
|
+
line carries a **count as a screen** button, as every row of the table carries a **not a screen** one:
|
|
902
|
+
telling a screen from a piece of one is partly done by reading file names, and no set of names fits
|
|
903
|
+
every project. A reclassified entry is remembered with the session.
|
|
904
|
+
|
|
905
|
+
### The other files, all optional
|
|
906
|
+
|
|
907
|
+
| File | What is read |
|
|
908
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
909
|
+
| `browser/` folder | Every `.js` and `.css` is gzipped with `CompressionStream` for real figures |
|
|
910
|
+
| `.js.br` / `.css.br` in that folder | Their size on disk **is** the brotli figure: read, never decompressed |
|
|
911
|
+
| `.js.map` in that folder | A second measurement of what each file weighs inside each chunk |
|
|
912
|
+
| `index.html` in that folder | Which chunks the page announces, for the round trips of the first load (§2.9) |
|
|
913
|
+
| Previous `stats.json` or a Loadline export | Baseline: bootstrap, its packages, the cost per screen, the signals raised and every file name with what it weighs and what it is mostly made of |
|
|
914
|
+
| Previous build folder | Compressed baseline: its `stats.json` analysed with its `.js` files compressed here |
|
|
915
|
+
| `loadline.json` | Thresholds, gates, accepted signals and the five answers |
|
|
916
|
+
| `angular.json` | `budgets` in `options` and in each configuration, `defaultConfiguration`, `polyfills` |
|
|
917
|
+
| `package.json` | `scripts` (to follow the pipeline's commands), `zone.js` and `@angular/core` |
|
|
918
|
+
| `.gitlab-ci.yml` / GitHub workflow | Commands containing `ng build` or a build script, with the job they live in |
|
|
919
|
+
|
|
920
|
+
The page's "Export analysis" button and the command's `--export` write the same file. That matters
|
|
921
|
+
more than it sounds: a `stats.json` is the only baseline a build can produce on its own, and Vite,
|
|
922
|
+
Rollup, SvelteKit, Nuxt, Astro and Solid do not write one — so before `--export` the only way to get a
|
|
923
|
+
baseline for any of them was to open a browser and press a button, which a pipeline cannot do.
|
|
924
|
+
|
|
925
|
+
The pipeline file is read without a YAML parser, line by line, which is why every command found is
|
|
926
|
+
shown in the Project tab with what it resolves to: if the heuristic gets it wrong, it shows.
|
|
927
|
+
|
|
928
|
+
### How `loadline.json` is allowed to grow
|
|
929
|
+
|
|
930
|
+
The file is `version: 1`, and the rule is that **every addition is an optional block and the version
|
|
931
|
+
stays at 1**. Bumping it buys nothing when everything entering is optional — a file written last month
|
|
932
|
+
is still valid word for word, and a bump would make the command carry two readers to express that
|
|
933
|
+
nothing broke. The line is where an old file would stop being valid: that is a new version.
|
|
934
|
+
|
|
935
|
+
One thing deliberately never goes in it: **anything measured from a browser**. Those facts have a date
|
|
936
|
+
and a machine attached and they go stale, and a stale figure committed to a repository is a false fact
|
|
937
|
+
with the shape of a measurement. The five answers are the opposite case and do go in — properties of a
|
|
938
|
+
team, the same for everybody who runs the command, and the kind of thing that should be argued about
|
|
939
|
+
in a review rather than retyped by each person who opens the report. They expire after a year, and the
|
|
940
|
+
report says so when they have.
|
|
941
|
+
|
|
942
|
+
An answer nobody recognises becomes "unanswered" plus a line to print, the same as an acceptance with
|
|
943
|
+
no reason: an answer is the only thing in this file that can move a colour, so it is the one mistake
|
|
944
|
+
that would otherwise change a verdict silently.
|
|
945
|
+
|
|
946
|
+
---
|
|
947
|
+
|
|
948
|
+
## 6. Design decisions
|
|
949
|
+
|
|
950
|
+
**One HTML file, no dependencies.** Opened by double-clicking. Nothing to install, update or maintain,
|
|
951
|
+
and it will still work in ten years.
|
|
952
|
+
|
|
953
|
+
**Everything in the browser.** A private app's `stats.json` reveals its routes, its dependencies and
|
|
954
|
+
its internal structure. It has no business leaving your machine.
|
|
955
|
+
|
|
956
|
+
**The last measurement is remembered, locally.** Loading anything stores it in the browser's IndexedDB
|
|
957
|
+
— the raw `stats.json`, the compressed sizes, the baseline and the context — and the next visit offers
|
|
958
|
+
to restore or forget it. Same privacy rule, now with memory.
|
|
959
|
+
|
|
960
|
+
**The bar's three segments are the message.** Colour is not decoration: slate is the unavoidable
|
|
961
|
+
baseline, burnt orange is what everyone pays, teal is this screen's own. On a shared scale, the
|
|
962
|
+
alignment of the orange block tells the story without a single number.
|
|
963
|
+
|
|
964
|
+
**Signals come with their fix**, including warnings about what **not** to do. Data with no "so what"
|
|
965
|
+
is useless.
|
|
966
|
+
|
|
967
|
+
**Three kinds of fact, never mixed in one sentence.** Something is **derived** from the build (exact
|
|
968
|
+
about what was built, silent about what is served), **measured** by a browser (one machine, one
|
|
969
|
+
connection, one day), or **declared** by somebody (worth more than a guess and less than a
|
|
970
|
+
measurement). The fourth state is **unknown**, and it is the one that matters: a report that quietly
|
|
971
|
+
turns "nobody looked" into "we assumed the median" cannot be checked, so `unknown` has a word of its
|
|
972
|
+
own and never a value.
|
|
973
|
+
|
|
974
|
+
**Evidence may raise a severity and only evidence may lower one.** The failure mode of the symmetric
|
|
975
|
+
version is that an optimistic answer produces silence exactly where the honest answer is noise, and
|
|
976
|
+
silence is the one output nobody checks. A test over every combination of the five answers keeps it
|
|
977
|
+
that way (§3.22).
|
|
978
|
+
|
|
979
|
+
**The report never filters.** Context reorders, re-thresholds and rewords; no finding is ever hidden.
|
|
980
|
+
A signal the page hides is a signal nobody can look at, and the page is where somebody goes **to**
|
|
981
|
+
look. Accepting a signal is a decision for the pipeline, and it is printed under the report either
|
|
982
|
+
way.
|
|
983
|
+
|
|
984
|
+
**The size budget is on one file.** Because the tool is one self-contained HTML, a lazy chunk would
|
|
985
|
+
either break the double-click property or be inlined back into the same file, moving the number
|
|
986
|
+
without moving a byte. So the budget in `angular.json` is an alarm on the whole thing. Loadline
|
|
987
|
+
pointed at its own build says where the weight is: the signal copy in two languages, and two woff2
|
|
988
|
+
fonts as data URIs so the page never reaches the network. Both are properties this project chose, and
|
|
989
|
+
the lever that would shrink it — shipping one language per build — costs the language toggle.
|
|
990
|
+
|
|
991
|
+
### How the source is laid out
|
|
992
|
+
|
|
993
|
+
```
|
|
994
|
+
src/app/core/ the analysis itself: no Angular anywhere in it, and where the tests are
|
|
995
|
+
src/app/state/ the Angular services holding what is loaded and what derives from it
|
|
996
|
+
src/app/shared/ pieces used by more than one screen: the bytes pipe, the trees, the tag
|
|
997
|
+
src/app/features/ what you look at: the drop zone, the report and its nine panels
|
|
998
|
+
```
|
|
999
|
+
|
|
1000
|
+
**`core/` never imports Angular.** That is what lets the whole analysis be tested by calling a function
|
|
1001
|
+
with an object, without a browser or an injector. Everything that computes something carries its own
|
|
1002
|
+
`.spec.ts`; what is left is data, type declarations and the browser storage the last session is kept
|
|
1003
|
+
in.
|
|
1004
|
+
|
|
1005
|
+
**A panel holds its own state, never another panel's.** What two panels have to agree on — which tab
|
|
1006
|
+
is open, which row to reveal — goes through `ReportNav`, and everything derived from the loaded files
|
|
1007
|
+
hangs from `ReportStore` as a computed. That is why switching language does not walk the dependency
|
|
1008
|
+
graph again: the analysis does not depend on the language, and the signals do.
|
|
1009
|
+
|
|
1010
|
+
**Text lives apart from the code that decides.** `core/i18n/` holds the interface both languages fill
|
|
1011
|
+
(`ui-strings.ts`) and one file per language; `core/findings/` separates when a signal fires
|
|
1012
|
+
(`findings.ts`) from what it says (`finding-text.ts`). Rewording a signal touches no rule.
|
|
1013
|
+
|
|
1014
|
+
**Shapes live apart from the code that fills them.** A type another file imports goes in a `.types.ts`
|
|
1015
|
+
next to its module: `analysis.ts` computes, `analysis.types.ts` says what comes out. The point is the
|
|
1016
|
+
reading order — a module opens on its first function instead of two hundred lines of declarations.
|
|
1017
|
+
Types that never leave their file stay in it, and so does the input contract of a component.
|
|
1018
|
+
|
|
1019
|
+
**Three path aliases, one per layer**, declared in `tsconfig.json`: `@core/*`, `@shared/*` and
|
|
1020
|
+
`@state/*`, for imports that would otherwise climb. Siblings and one level up stay relative.
|
|
1021
|
+
`features/` has no alias on purpose: inside a screen everything is a sibling, and an alias there would
|
|
1022
|
+
invite one panel to import another.
|
|
1023
|
+
|
|
1024
|
+
---
|
|
1025
|
+
|
|
1026
|
+
## 7. What the other tools do
|
|
1027
|
+
|
|
1028
|
+
Checked on 2026-09-01 against each tool's documentation. Loadline does not replace these: it answers a
|
|
1029
|
+
question none of them answers, and leaves out things several of them do well.
|
|
1030
|
+
|
|
1031
|
+
| Tool | Input | What it adds | What it lacks compared to Loadline |
|
|
1032
|
+
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
1033
|
+
| [esbuild Bundle Size Analyzer](https://esbuild.github.io/analyze/) (official) | metafile | Treemap of what each chunk weighs and which files it contains. Nothing to install. | Nothing per screen. Doesn't know how many screens load a chunk. No real gzip, no comparison, no budgets. |
|
|
1034
|
+
| [Hawkeye](https://angularexperts.io/blog/hawkeye-esbuild-analyzer/) (Angular Experts) | `stats.json` | Separates eager from lazy, searches a library and says whether it lands in the eager or lazy part. | Still "what is in each chunk". No per-screen figure, no screens-per-chunk count, no gzip, comparison or budgets. |
|
|
1035
|
+
| [Sonda](https://sonda.dev/frameworks/angular-cli) | `stats.json` + source maps | Treemap and dependency tree, gzip **and brotli**, JSON report for CI. Measures on the final minified file. | Requires source maps and a command. No per-screen weight, no "lazy that is really common". No build comparison. |
|
|
1036
|
+
| [source-map-explorer](https://www.npmjs.com/package/source-map-explorer) | source maps | Exact bytes of each source file inside the final file. | Only that: a treemap per output file. |
|
|
1037
|
+
| [@rnx-kit/esbuild-bundle-analyzer](https://www.npmjs.com/package/@rnx-kit/esbuild-bundle-analyzer) | metafile | Duplicates **with the import chain** each copy enters through. **Compares two metafiles.** | Terminal only, uncompressed figures, nothing per screen. |
|
|
1038
|
+
| [exoego/esbuild-bundle-analyzer](https://github.com/exoego/esbuild-bundle-analyzer), [build-size-diff](https://github.com/q1sh101/build-size-diff) | metafile / output folder, in CI | GitHub Action: comments on the PR how much each output file changed against the base branch. | They compare files, not screens. They don't say "this screen grew because a shared chunk grew". |
|
|
1039
|
+
| [Statoscope](https://github.com/statoscope/statoscope) | webpack stats | The only one with "download size per entry point" and validation rules between two builds. | Webpack only. Angular 17+ uses esbuild; [the support request](https://github.com/statoscope/statoscope/issues/148) is still open. |
|
|
1040
|
+
| [Bundle Buddy](https://github.com/Timer/bundle-buddy) | source maps | Source code repeated across chunks, at line level. | Only that. |
|
|
1041
|
+
| [bundle-stats](https://github.com/relative-ci/bundle-stats) | webpack, rspack, vite, rollup | Per-build report with history and comparison. | Doesn't read esbuild metafiles or Angular CLI. |
|
|
1042
|
+
| Angular CLI (`ng build`) | — | Table of initial and lazy chunks; enforces the `budgets` in `angular.json`. | No per-screen total. The budget only applies in the configuration being built; nobody checks whether the pipeline builds that one. |
|
|
1043
|
+
|
|
1044
|
+
### 7.1 What Loadline does that none of them does
|
|
1045
|
+
|
|
1046
|
+
- The per-screen figure (bootstrap + shared + own), by walking the import graph from each lazy route.
|
|
1047
|
+
- Counting how many screens load each "lazy" chunk. The problem is documented — esbuild produces many
|
|
1048
|
+
shared chunks, and the Angular team has an
|
|
1049
|
+
[experimental chunk optimizer](https://push-based.io/article/faster-builds-slower-applications-optimizing-angulars-bundle-output)
|
|
1050
|
+
— but no tool diagnoses it per screen.
|
|
1051
|
+
- Cross-checking the `angular.json` budgets against which configuration the pipeline builds.
|
|
1052
|
+
- Real gzip measured in the browser, without source maps and without installing anything.
|
|
1053
|
+
- Searching a name and seeing, besides where it lands, **which screens pay for it**.
|
|
1054
|
+
|
|
1055
|
+
### 7.2 What they do that Loadline does not
|
|
1056
|
+
|
|
1057
|
+
- **Post the comment on the PR.** The command writes it (`--format pr-comment`) and exits non-zero
|
|
1058
|
+
when a limit breaks, but some job of yours has to post it. The GitHub Actions and Statoscope do that
|
|
1059
|
+
last step themselves.
|
|
1060
|
+
- **Line-level duplication across chunks** (Bundle Buddy). Loadline works at file and package level.
|
|
1061
|
+
Not started on purpose: comparing everything with everything is expensive inside the browser, and
|
|
1062
|
+
the typical finding — a copied utility — usually weighs little.
|
|
1063
|
+
- **Webpack** (Statoscope, webpack-bundle-analyzer, bundle-stats). Loadline reads an esbuild metafile
|
|
1064
|
+
or a folder of ES modules, and webpack is neither: it resolves imports at run time through
|
|
1065
|
+
`__webpack_require__`, so there is nothing in the shipped file to read. That leaves out Angular 16
|
|
1066
|
+
and earlier, Next.js and Create React App.
|
|
1067
|
+
|
|
1068
|
+
### 7.3 One finding worth keeping
|
|
1069
|
+
|
|
1070
|
+
Reading source maps was added to close the gap against Sonda and source-map-explorer, and the result
|
|
1071
|
+
changed the reason for doing it. The premise was that the metafile measures **before** minification,
|
|
1072
|
+
which is true of webpack stats — what those tools were written for — and **not** of the esbuild
|
|
1073
|
+
metafile: measured on a real build of Loadline, the sum of `bytesInOutput` was 99.9 % of the generated
|
|
1074
|
+
file, while the source bytes of those same files added up to 6.2 times that size. The split was
|
|
1075
|
+
already sound, and the "approximate" label was unwarranted.
|
|
1076
|
+
|
|
1077
|
+
That measurement has since expired on some builds, and the maps being an independent second
|
|
1078
|
+
measurement is what caught it (§3.23). One detail came out of it as well: the maps attribute a
|
|
1079
|
+
component's template to its `.html`, while the metafile counts it inside the `.ts`. Without folding one
|
|
1080
|
+
into the other, a component with a big template came out at 58 % of its real weight.
|
|
1081
|
+
|
|
1082
|
+
### 7.4 Caveats
|
|
1083
|
+
|
|
1084
|
+
- What is said about Hawkeye comes from its authors' article; its GitHub README could not be read
|
|
1085
|
+
during the check. A recent version adding per-route weight would not show here.
|
|
1086
|
+
- Comparing two builds and detecting duplicates exist elsewhere (rnx-kit, GitHub Actions). What
|
|
1087
|
+
Loadline adds there is doing it per screen and without leaving the browser.
|