@bymaksym/loadline 1.0.0 → 1.2.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/README.md +229 -43
- package/dist/cli/cli/args.js +79 -128
- package/dist/cli/cli/gates.js +80 -14
- package/dist/cli/cli/main.js +164 -33
- package/dist/cli/cli/memory.js +40 -4
- package/dist/cli/cli/{declared.js → read/declared.js} +1 -1
- package/dist/cli/cli/read/locate.js +214 -0
- package/dist/cli/cli/{read-build.js → read/read-build.js} +149 -84
- package/dist/cli/cli/read/read-config.js +120 -0
- package/dist/cli/cli/{html-report.js → render/html-report.js} +14 -10
- package/dist/cli/cli/render/render-agent.js +114 -0
- package/dist/cli/cli/render/render-asked.js +104 -0
- package/dist/cli/cli/render/render-badge.js +140 -0
- package/dist/cli/cli/{render-json.js → render/render-json.js} +18 -5
- package/dist/cli/cli/{render-markdown.js → render/render-markdown.js} +5 -5
- package/dist/cli/cli/{render-pr.js → render/render-pr.js} +33 -13
- package/dist/cli/cli/{render-sarif.js → render/render-sarif.js} +8 -3
- package/dist/cli/cli/{render-text.js → render/render-text.js} +118 -111
- package/dist/cli/cli/render/terminal.js +55 -0
- package/dist/cli/cli/report.js +68 -27
- package/dist/cli/cli/self-check.js +19 -23
- package/dist/cli/cli/since-last.js +2 -2
- package/dist/cli/cli/text/text-errors.js +124 -0
- package/dist/cli/cli/text/text.js +343 -0
- package/dist/cli/cli/text/usage.js +240 -0
- package/dist/cli/src/app/core/analysis/analysis.js +63 -23
- package/dist/cli/src/app/core/analysis/{barrels.js → graph/barrels.js} +1 -1
- package/dist/cli/src/app/core/analysis/{blast.js → graph/blast.js} +56 -17
- package/dist/cli/src/app/core/analysis/{cycles.js → graph/cycles.js} +1 -1
- package/dist/cli/src/app/core/analysis/{importers.js → graph/importers.js} +1 -1
- package/dist/cli/src/app/core/analysis/{insights.js → graph/insights.js} +10 -4
- package/dist/cli/src/app/core/analysis/invariant.js +1 -1
- package/dist/cli/src/app/core/analysis/metafile.types.js +7 -1
- package/dist/cli/src/app/core/analysis/{delivery.js → screens/delivery.js} +1 -1
- package/dist/cli/src/app/core/analysis/{entries.js → screens/entries.js} +50 -9
- package/dist/cli/src/app/core/analysis/screens/marks.js +32 -0
- package/dist/cli/src/app/core/analysis/screens/route-files.js +116 -0
- package/dist/cli/src/app/core/analysis/{sourcemap.js → sourcemap/sourcemap.js} +106 -7
- package/dist/cli/src/app/core/analysis/{split-drift.js → sourcemap/split-drift.js} +1 -1
- package/dist/cli/src/app/core/analysis/tool.js +83 -0
- package/dist/cli/src/app/core/assets/assets.js +134 -15
- package/dist/cli/src/app/core/baseline/baseline.js +0 -0
- package/dist/cli/src/app/core/{intake → build-text}/index-html.js +168 -13
- package/dist/cli/src/app/core/build-text/route-table.js +178 -0
- package/dist/cli/src/app/core/build-text/tool-marks.js +54 -0
- package/dist/cli/src/app/core/caching/caching.js +121 -43
- package/dist/cli/src/app/core/caching/from-analysis.js +20 -4
- package/dist/cli/src/app/core/config/config-text.js +90 -0
- package/dist/cli/src/app/core/config/config-values.js +358 -0
- package/dist/cli/src/app/core/config/loadline-config.js +81 -16
- package/dist/cli/src/app/core/config/merge-config.js +98 -0
- package/dist/cli/src/app/core/deps/deps.js +104 -16
- package/dist/cli/src/app/core/export/summary.js +29 -5
- package/dist/cli/src/app/core/findings/actions.js +3 -1
- package/dist/cli/src/app/core/findings/{boot-single.js → bundle/boot-single.js} +3 -3
- package/dist/cli/src/app/core/findings/{dupes.js → bundle/dupes.js} +8 -5
- package/dist/cli/src/app/core/findings/{graph.js → bundle/graph.js} +30 -18
- package/dist/cli/src/app/core/findings/{own-in-boot.js → bundle/own-in-boot.js} +9 -5
- package/dist/cli/src/app/core/findings/{requests.js → bundle/requests.js} +3 -3
- package/dist/cli/src/app/core/findings/{shipped.js → bundle/shipped.js} +28 -14
- package/dist/cli/src/app/core/findings/compose.js +6 -1
- package/dist/cli/src/app/core/findings/effort.js +2 -0
- package/dist/cli/src/app/core/findings/finding.types.js +1 -0
- package/dist/cli/src/app/core/findings/findings.js +48 -19
- package/dist/cli/src/app/core/findings/{assets.js → folder/assets.js} +38 -14
- package/dist/cli/src/app/core/findings/{caching.js → folder/caching.js} +16 -9
- package/dist/cli/src/app/core/findings/{page.js → folder/page.js} +6 -2
- package/dist/cli/src/app/core/findings/{scan.js → folder/scan.js} +25 -11
- package/dist/cli/src/app/core/findings/kind-names.js +163 -0
- package/dist/cli/src/app/core/findings/{deps.js → supplied/deps.js} +13 -8
- package/dist/cli/src/app/core/findings/supplied/forbidden.js +71 -0
- package/dist/cli/src/app/core/findings/{situation.js → supplied/situation.js} +2 -2
- package/dist/cli/src/app/core/findings/text/causes.js +39 -0
- package/dist/cli/src/app/core/findings/{finding-html.js → text/finding-html.js} +8 -1
- package/dist/cli/src/app/core/findings/{finding-text.js → text/finding-text.js} +208 -77
- package/dist/cli/src/app/core/findings/text/tool-advice.js +97 -0
- package/dist/cli/src/app/core/format/format.utils.js +158 -11
- package/dist/cli/src/app/core/format/ownership.js +93 -0
- package/dist/cli/src/app/core/i18n/en.js +76 -17
- package/dist/cli/src/app/core/i18n/es.js +82 -22
- package/dist/cli/src/app/core/intake/bundle-graph.js +281 -43
- package/dist/cli/src/app/core/intake/dist-files.js +82 -14
- package/dist/cli/src/app/core/intake/embedded.js +11 -1
- package/dist/cli/src/app/core/intake/unreached.js +139 -0
- package/dist/cli/src/app/core/intake/webpack-modules.js +185 -0
- package/dist/cli/src/app/core/intake/webpack-stats.js +298 -0
- package/dist/cli/src/app/core/project/project-context.js +16 -4
- package/dist/cli/src/app/core/project/project-name.js +36 -0
- package/dist/cli/src/app/core/scan/scan.js +58 -19
- package/dist/cli/src/app/core/scan/secrets.js +23 -3
- package/dist/cli/src/app/core/situation/situation-text.js +23 -0
- package/dist/cli/src/app/core/situation/situation.js +6 -4
- package/dist/cli/src/app/core/timing/timing.js +5 -2
- package/dist/cli/src/app/core/whatif/defer.js +29 -4
- package/dist/cli/src/app/core/whatif/source-importers.js +58 -0
- package/dist/cli/src/app/core/whatif/why.js +102 -0
- package/docs/CONFIG-REFERENCE.md +230 -0
- package/docs/CONFIG.md +511 -0
- package/docs/HOW-IT-WORKS.md +286 -25
- package/loadline.html +24 -20
- package/loadline.schema.json +1209 -0
- package/package.json +35 -29
- package/dist/cli/cli/locate.js +0 -60
- package/dist/cli/cli/text.js +0 -215
- /package/dist/cli/cli/{read-build.types.js → read/read-build.types.js} +0 -0
- /package/dist/cli/cli/{render-json.types.js → render/render-json.types.js} +0 -0
- /package/dist/cli/cli/{text.types.js → text/text.types.js} +0 -0
- /package/dist/cli/src/app/core/analysis/{exclusive.js → graph/exclusive.js} +0 -0
- /package/dist/cli/src/app/core/analysis/{insights.types.js → graph/insights.types.js} +0 -0
- /package/dist/cli/src/app/core/analysis/{module-graph.js → graph/module-graph.js} +0 -0
- /package/dist/cli/src/app/core/analysis/{sourcemap.types.js → sourcemap/sourcemap.types.js} +0 -0
- /package/dist/cli/src/app/core/findings/{finding-plain.js → text/finding-plain.js} +0 -0
package/docs/HOW-IT-WORKS.md
CHANGED
|
@@ -104,6 +104,23 @@ Three more rules joined them:
|
|
|
104
104
|
- **Data is not a screen.** `import('./locales/ru-RU.json')` produces a lazy entry exactly like a
|
|
105
105
|
route does. Excalidraw lazy-loads fifty languages, and its table came out with sixty-one rows for
|
|
106
106
|
an application with one screen. Data entries are listed separately.
|
|
107
|
+
- **Where the code has a route table, the table decides.** Read from a build folder, the chunks still
|
|
108
|
+
carry the router's table, because its keys are the router's API and no minifier renames them: an
|
|
109
|
+
object with a `path` and a `component`, `loadComponent`, `loadChildren`, `lazy`, `getComponent` or
|
|
110
|
+
`asyncComponent` whose value imports the chunk (`core/build-text/route-table.ts`); a router that
|
|
111
|
+
uses another word is named in `build.routeKeys`. Stencil's loader lists its components the same
|
|
112
|
+
way — the id of each chunk and the tag it defines — and is read as its table: components named by
|
|
113
|
+
their tag, and the polyfills it fetches for old browsers, which it does not list, no screens.
|
|
114
|
+
Sapper's manifest has none of those shapes — a list of components, `{js:()=>import("./index.e902f999.js")}`,
|
|
115
|
+
and a list of routes, each a regular expression and its page by place in the first list — and is
|
|
116
|
+
read too: the expression gives the path, its groups named by the route's parameters
|
|
117
|
+
(`/profile/[user]/[view]`). Without it, a Sapper build without source maps had seven screens called
|
|
118
|
+
`index`, told apart by their hashes. With two routes found, a lazy chunk
|
|
119
|
+
a route imports is a screen, named after the route when there is no source map to name it, and one
|
|
120
|
+
no route imports is not: Nuxt without maps listed fourteen language files and its i18n config as
|
|
121
|
+
screens named after hashes, and PocketBase listed seventeen documentation tabs. Without a table,
|
|
122
|
+
every lazy chunk stays a screen as before, and the report says it found none — a stats file has
|
|
123
|
+
no code to look in, so it says nothing then.
|
|
107
124
|
|
|
108
125
|
### 2.4 Splitting the cost
|
|
109
126
|
|
|
@@ -140,7 +157,14 @@ report is in compressed figures. To keep the two units from being confused, the
|
|
|
140
157
|
its raw size under the compressed one, and the head of its file tree says `raw` and how much of the
|
|
141
158
|
chunk is unattributed. Those bytes are the bundler's own code — module wrapper, banners — which
|
|
142
159
|
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).
|
|
160
|
+
the two measurements agree, which is checked rather than assumed (§3.23).
|
|
161
|
+
|
|
162
|
+
A signal that puts a figure from inside a chunk in a sentence gives it in the report's unit anyway, at
|
|
163
|
+
the ratio the bytes around it compress by and with `≈`: "≈80 kB of dependencies" for the chunks that
|
|
164
|
+
mix them with your code, the share of the chunk's own compressed size; packages against your own code
|
|
165
|
+
in the first load, at the ratio the bootstrap compresses by. Given raw, a gzip report said "283 kB
|
|
166
|
+
re-invalidated" and "268 kB of packages" over an 87 kB bootstrap, and the first of those was being
|
|
167
|
+
compared against a threshold in gzip. Other tools
|
|
144
168
|
(`esbuild-visualizer`, Sonda) show the raw figure as the chunk's headline, which is why their numbers
|
|
145
169
|
look nothing like Loadline's until both are read in the same unit.
|
|
146
170
|
|
|
@@ -220,7 +244,7 @@ chunks, the question none of them answers is whether the build is **well divided
|
|
|
220
244
|
|
|
221
245
|
That is not a property of any row. More chunks is not better and fewer is not better: what matters is
|
|
222
246
|
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:
|
|
247
|
+
is measured on the distribution (`core/analysis/screens/shape.ts`), with two numbers per zone:
|
|
224
248
|
|
|
225
249
|
- **Concentration**: how much of a zone sits in its largest chunk. Fifteen shared chunks where one
|
|
226
250
|
holds 93 % is a different situation from fifteen even ones, and a list of fifteen rows hides it.
|
|
@@ -272,6 +296,11 @@ was loaded with that page; without it, Loadline says "not known" rather than pri
|
|
|
272
296
|
from the wrong thing. The page is read with regular expressions rather than `DOMParser`, so the
|
|
273
297
|
command and the browser read it the same way.
|
|
274
298
|
|
|
299
|
+
The command's **whole first trip** — everything downloaded before anything appears — counts those
|
|
300
|
+
late chunks too. Read off `index.html` alone it left them out, and a real Angular build printed "the
|
|
301
|
+
whole first trip is 133 kB" under a 464 kB bootstrap: the 346 kB missing was the very chunk that made
|
|
302
|
+
the first load take two trips. Late or not, it arrives before the first paint.
|
|
303
|
+
|
|
275
304
|
---
|
|
276
305
|
|
|
277
306
|
## 3. The signals
|
|
@@ -336,6 +365,11 @@ moved nothing.
|
|
|
336
365
|
Only a copy that actually weighs something in some chunk counts: a version resolved but tree-shaken
|
|
337
366
|
away is not paid twice.
|
|
338
367
|
|
|
368
|
+
The version comes from the pnpm directory name, which carries more than the version: the peers it was
|
|
369
|
+
resolved against, or a hash of them — `@angular+material@22.1.6_2ffb4168…` — and, on a name too long
|
|
370
|
+
for the disk, a cut — `@angular+platform-browser@2_49839d…`. Only a whole `x.y.z` at its head is taken;
|
|
371
|
+
the cut one is given no version rather than `2`.
|
|
372
|
+
|
|
339
373
|
### 3.5 Expensive screen
|
|
340
374
|
|
|
341
375
|
**Fires when** a screen carries more than 6× the median of its own code, and over 100 kB.
|
|
@@ -348,13 +382,35 @@ _inside_ the screen — a viewer, an editor, a chart — it belongs in a deferre
|
|
|
348
382
|
These fire only with a baseline loaded: the previous build's `stats.json`, a Loadline export, or the
|
|
349
383
|
whole previous build folder. Both measurements are always compared in the same mode — a bare previous
|
|
350
384
|
`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
|
-
|
|
385
|
+
against compressed, give the previous folder: with its `stats.json` (or `browser-stats.json`) inside, or
|
|
386
|
+
without one, in which case its graph is read from its chunks as the build on screen is. The page used
|
|
387
|
+
to refuse a previous folder without `stats.json`, which left every Vite build without a way to be
|
|
388
|
+
compared there, and it did not know the name Angular gives that file from 22.2 on.
|
|
389
|
+
|
|
390
|
+
- **The bootstrap has grown** — by 10 % and 10 kB or more, editable under Criteria. It also says
|
|
391
|
+
**where the growth comes from**: the packages and the folders of your own code that entered, left,
|
|
392
|
+
grew or shrank in the bootstrap, biggest first, up to five. The delta alone answered "how much";
|
|
393
|
+
the question on a merge request is "what did I add", and before this it was answered by opening
|
|
394
|
+
two reports side by side. The weights are raw bytes per package, shown in the report's unit at the
|
|
395
|
+
ratio the bootstrap compresses by — `≈`, like every saving. A move under 512 raw bytes is left
|
|
396
|
+
out as noise. Own folders are compared only when both snapshots record them; against an export
|
|
397
|
+
older than that, the list is packages only, and says so, rather than reading every folder of the
|
|
398
|
+
project as new.
|
|
354
399
|
- **A package has entered the bootstrap** — an npm package that was not in the baseline's. Project
|
|
355
400
|
folders do not count: they change with every commit.
|
|
356
401
|
- **A screen has grown** — shared + own is compared, **without the bootstrap**. Comparing totals, a
|
|
357
|
-
bigger bootstrap would flag all twenty screens at once.
|
|
402
|
+
bigger bootstrap would flag all twenty screens at once. Each screen it names also says **where its
|
|
403
|
+
growth comes from**, by the bootstrap's rules: the packages and own folders that moved in the
|
|
404
|
+
chunks that screen loads beyond the bootstrap, up to three per screen, raw weights shown at the
|
|
405
|
+
ratio _that screen_ compresses by. "`reports` +120 kB" sent the person to open two reports;
|
|
406
|
+
"`xlsx` ≈+118 kB (new)" is the answer. It needs both snapshots to carry the screen's breakdown:
|
|
407
|
+
against an older export, or a build that did not say what is inside its chunks, the screen is
|
|
408
|
+
named without causes rather than with every package of it read as new.
|
|
409
|
+
|
|
410
|
+
The bootstrap follows the same rule. A snapshot of a folder read without source maps records an
|
|
411
|
+
empty list of packages next to a bootstrap of 200 kB: not "nothing", "not known". Against one, the
|
|
412
|
+
growth is given without causes and no package is said to have entered — before, a real build reported
|
|
413
|
+
`@angular/core` as new against its own previous version.
|
|
358
414
|
|
|
359
415
|
⚠️ **One trap remains**: when a near-global shared chunk grows, every screen loading it goes up by the
|
|
360
416
|
same amount — in one real app, 19 screens at "+247 kB". So when most screens grow by about the same
|
|
@@ -542,6 +598,9 @@ file — `0fPdmq0U.js` rather than `orders` — and there is no breakdown by pac
|
|
|
542
598
|
entry point. Everything else comes out in full. It exists because two real builds, elk and immich,
|
|
543
599
|
neither of which publishes maps, came out as a page of hashes with nothing to explain them.
|
|
544
600
|
|
|
601
|
+
With it, "nothing stands out" is not said: that card vouches for the breakdown — no package shipped
|
|
602
|
+
twice — and there is no breakdown to vouch for.
|
|
603
|
+
|
|
545
604
|
### 3.18 What the report cannot reach
|
|
546
605
|
|
|
547
606
|
**Fires when** some JavaScript of the build is imported by nothing reachable from the entry point, by
|
|
@@ -573,7 +632,16 @@ single-page application is nearly everything. It does not grow with depth; it ju
|
|
|
573
632
|
this build — which chunk names the most others, and how many name it — and reported as LOW, MID or
|
|
574
633
|
HIGH with the reason. LOW is the runtime-chunk shape, which is what webpack emits and what largely
|
|
575
634
|
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.
|
|
635
|
+
has to be tiny and inlined, or the cost comes straight back. That caveat is for a chunk of the first
|
|
636
|
+
load: when the small chunk holding the names is lazy, as in Angular RealWorld, it comes with the
|
|
637
|
+
screen that needs it, there is no page to inline it into, and the advice is to keep it small.
|
|
638
|
+
|
|
639
|
+
**A name without a hash stops it.** The cascade travels through names that change, and a chunk written
|
|
640
|
+
as `index.js` changes its content on every edit below it and never its name. Solid's Rollup template
|
|
641
|
+
ships exactly that, and the report said "touching any leaf moves the whole build" of a build where the
|
|
642
|
+
eight chunks importing `index.js` never change for it. Those edges are not followed. One large file
|
|
643
|
+
naming most of the build while few chunks carry its name is then its own shape, and said as such: a
|
|
644
|
+
change stops at that file, and what it costs is the file.
|
|
577
645
|
|
|
578
646
|
**With a baseline it stops being a model.** Two builds diffed by file name _are_ the delta a browser
|
|
579
647
|
would pay. The changed files split into the ones where the edit landed and the ones that only moved
|
|
@@ -754,6 +822,31 @@ file itself. On the same Angular 22 probe, the graph walk over the metafile alon
|
|
|
754
822
|
against a 222 555-byte bootstrap (**+26 %**); with the maps alongside it, 221 555 (**−0.45 %**). It
|
|
755
823
|
does not fire on chunks a map covered, because for those there is nothing left to drift.
|
|
756
824
|
|
|
825
|
+
### 3.24 What `loadline.json` forbids
|
|
826
|
+
|
|
827
|
+
**Fires when** a rule of `forbidden` matches a file of the build: a package by name, or files of the
|
|
828
|
+
project by path, anywhere in the build or — with `"in": "bootstrap"` — in the first load. One signal
|
|
829
|
+
per rule, `high` whatever the size.
|
|
830
|
+
|
|
831
|
+
Every other signal is this tool's opinion of a build. This one is the team's, written down, and the
|
|
832
|
+
tool only says where it is broken and which import breaks it. That is why the size does not decide
|
|
833
|
+
the severity: a 2 kB locale of `moment` breaks "no moment" exactly as much as the whole library, and
|
|
834
|
+
a threshold under which a forbidden package passes would be a second rule nobody wrote.
|
|
835
|
+
|
|
836
|
+
**Declarative, not code.** The obvious alternative was the ESLint model — rules as plugins somebody
|
|
837
|
+
installs. A plugin cannot run in the page, which is one offline HTML file, so the page and the
|
|
838
|
+
command would judge the same `loadline.json` differently, which is the disagreement the file exists
|
|
839
|
+
to end. A rule over data the analysis already has — every file, its package and its zone — runs in
|
|
840
|
+
both. Patterns are `*` and nothing more, matched by hand like the ones of `build`: a regular
|
|
841
|
+
expression built from somebody's text is one more thing that can hang on a bundle of megabytes.
|
|
842
|
+
|
|
843
|
+
**An ordinary signal, on purpose.** Its key is the rule as written, so an exception is an entry in
|
|
844
|
+
`accepted` with a reason and a date, and failing on it is `failOn` or `failOnSignals`. dependency-cruiser
|
|
845
|
+
and Statoscope, the closest prior art, give their rules a severity of their own; here that would have
|
|
846
|
+
been a second, smaller version of the gates and of `accepted` living inside one block. Statoscope's
|
|
847
|
+
`restricted-packages` looks at the whole compilation: "never in the first load" is the part none of
|
|
848
|
+
them says.
|
|
849
|
+
|
|
757
850
|
---
|
|
758
851
|
|
|
759
852
|
## 4. Traps found while building it
|
|
@@ -806,7 +899,8 @@ which keeps its `path`; only `providers` and `loadComponent` move down to the ch
|
|
|
806
899
|
## 5. Data format
|
|
807
900
|
|
|
808
901
|
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
|
|
902
|
+
with `--stats-json` and by plain esbuild with its metafile option, and webpack's `stats.json`,
|
|
903
|
+
translated into one (below). The keys it uses:
|
|
810
904
|
|
|
811
905
|
| Key | What for |
|
|
812
906
|
| ---------------------------------- | --------------------------------------------------------------------------------- |
|
|
@@ -838,30 +932,157 @@ module bundle carries its graph in the code that ships:
|
|
|
838
932
|
so the entry ends up imported by its own children: there is no "chunk nobody imports" to find. Only
|
|
839
933
|
`index.html` can name it. It does so in one of two ways — a `<script src>`, or an `import()` inside
|
|
840
934
|
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:
|
|
935
|
+
- **A folder of webpack or Turbopack chunks is refused, and its stats file read instead.** Those builds have entry chunks and no graph:
|
|
842
936
|
their imports are numbers the loader resolves at run time. Read as ES modules, a Next.js export came
|
|
843
937
|
out as one bootstrap of seven files, zero screens and "nothing stands out" — confident, detailed and
|
|
844
|
-
false.
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
938
|
+
false. Before webpack 5 the runtime was called `webpackJsonp` (Create React App 1 to 3, Vue CLI), and
|
|
939
|
+
until it was known a webpack 4 build of three lazy routes read as one bootstrap of 1 kB and no
|
|
940
|
+
screens; `fixtures/webpack4-app` is that build. A webpack build of one chunk writes no runtime and is
|
|
941
|
+
still read: it has no graph to lose. A folder whose entry carries that runtime, where nothing imports anything lazily **and** where
|
|
942
|
+
another chunk registers with it is named for what it is. All three are needed: the marker alone
|
|
943
|
+
would refuse an ES bundle carrying one webpack-built dependency, no lazy edges alone is an ordinary
|
|
944
|
+
application with every route eager, and a runtime with nothing to load is ember-auto-import's
|
|
945
|
+
inside an Ember `vendor.js`, which was refused as Next.js.
|
|
946
|
+
- **Before ES modules the graph is still in the files, as strings.** AMD writes `define(["./a.js"], …)`
|
|
947
|
+
and SystemJS `System.register(["./a.js"], …)`: both are read as static edges, with `.js` tried when
|
|
948
|
+
the id leaves it off, as RequireJS and Rollup's `amd` output do. A page may start the application
|
|
949
|
+
from `data-main` or from a string in an inline script (`s.src="/client/client.1180.js"`, Sapper's
|
|
950
|
+
way) rather than a tag, and both count. Polymer's AMD build read as a 2 kB loader, zero screens
|
|
951
|
+
and 1.1 MB "in no figure here", and Sapper's was refused with "no index.html" next to its page.
|
|
952
|
+
- **Last, a chunk nothing imports but something names.** A loader older than `import()`, or one that
|
|
953
|
+
builds the file name at run time, keeps the names as plain strings: Stencil lists components as
|
|
954
|
+
`"p-w91mnxr1"` and loads `./${id}.entry.js`. A chunk no edge reaches, whose name — or, when it
|
|
955
|
+
looks like a hash, the part before its first dot — appears as a string in a chunk the application
|
|
956
|
+
reaches, is taken as loaded on demand by it. It only ever touches what nothing else reached, so
|
|
957
|
+
a build whose chunks are all reached reads exactly as before, and a plain word (`index`, `vendor`)
|
|
958
|
+
is never a name. A Stencil app went from zero screens and 33 of 36 chunks unaccounted for to its
|
|
959
|
+
components.
|
|
960
|
+
- **What no screen downloads is left out and counted**, the way the server side is: what only a
|
|
961
|
+
`<script nomodule>` (or the `catch` of an inline loader) reaches is the copy for old browsers, and
|
|
962
|
+
a service worker — registered in the page or the code — runs beside the page with what it
|
|
963
|
+
imports. Counted, a Stencil bootstrap was 48 kB of which 42 were its SystemJS fallback.
|
|
964
|
+
- **When the rules are wrong, `build` in `loadline.json` says it**: `entries`, `ignore`, `screens` and
|
|
965
|
+
`page`, file names with `*` ([Configuring Loadline](CONFIG.md#when-it-reads-your-build-wrong)). Every
|
|
966
|
+
rule here is a guess about how some tool writes a folder, and a tool that does something new will
|
|
967
|
+
get past them; the way through should not be a release. The page asks for `entries` where the
|
|
968
|
+
folder was refused, and the command takes it as `--entry`.
|
|
969
|
+
- **A folder comes in four ways, and all of them read the stats file inside it first.** Dropped,
|
|
970
|
+
chosen with the button, picked with the API that keeps it, or read again after a rebuild: webpack
|
|
971
|
+
writes its `stats.json` inside the folder it builds, and only the drop looked for it — the same
|
|
972
|
+
folder chosen with the button was refused with "put the stats file in the folder", where it was.
|
|
973
|
+
And a drop the browser will not list is said: Chrome, on a page opened from the disk, hands over
|
|
974
|
+
the folder and fails to read what is inside it, and the drop did nothing and said nothing. The
|
|
975
|
+
button reads the same folder there.
|
|
976
|
+
- **The same file under two names is a copy that travels or a copy that is stored.** Two names with
|
|
977
|
+
one content are two cache entries when the page or the code asks for both — Sapper links `main.css`
|
|
978
|
+
and its runtime loads `chunk.css`. When it asks for one or none, the second copy is never
|
|
979
|
+
downloaded and costs the deploy, not the visit: Stencil writes its global stylesheet as `app.css`
|
|
980
|
+
and again under a hash, the page asks for neither, and the report said a visitor downloads both.
|
|
848
981
|
- **Without `.js.map` the report loses the inside of each chunk**, and nothing else.
|
|
982
|
+
- **With them it still does not know who imports what.** A map says which source wrote each stretch
|
|
983
|
+
of a chunk; the `import` statements between those sources were erased by the bundler. So the chain
|
|
984
|
+
from the entry to a package, its exclusive weight, the files importing it, and what `--what-if`
|
|
985
|
+
would save are "not known" for a folder read alone — not "nobody imports it" and "0 B", which is
|
|
986
|
+
what a real build printed for `@angular/material`, 92 kB of its bootstrap. The `stats.json` has
|
|
987
|
+
the edges.
|
|
988
|
+
- **Without maps, a screen is named the way the bundler named its chunk.** Rollup, Vite and esbuild
|
|
989
|
+
name a chunk after the module it starts at and append an eight-character hash, so `Article-BZRh73np.js`
|
|
990
|
+
is the screen `Article`. A real Vue build had its table read `Article-BZRh73np` under a signal saying
|
|
991
|
+
every row was a hash nobody could read. A name that is only a hash (`0fPdmq0U.js`), or Angular's
|
|
992
|
+
`chunk-`, stays what it is, and that signal is for those.
|
|
993
|
+
- **"No source maps" is said of the folder only when no chunk of the bootstrap has one.** Vite writes no
|
|
994
|
+
map for the 84 bytes of `plugin-vue:export-helper`, and a folder with sixteen maps was announced as
|
|
995
|
+
having none, with every saving "not known". One chunk missing its map is named, with its weight.
|
|
996
|
+
Nor is a chunk with nothing of yours in it unknown: esbuild puts its runtime helpers in a chunk whose
|
|
997
|
+
`inputs` is `{}`, and an Angular build read with its `stats.json` was told it had no source maps.
|
|
998
|
+
- **A chunk is named after the module it starts at, not its template.** Angular names every chunk
|
|
999
|
+
`chunk-<hash>.js`, so the name says nothing, and the last source in the map is taken — the bundler
|
|
1000
|
+
writes the module a chunk exists for last. Angular lists a component's template after the
|
|
1001
|
+
component, so that was `orders.page.html`: templates and stylesheets are skipped.
|
|
1002
|
+
- **Angular's own maps point outside `node_modules/@angular`.** Its packages are built with Bazel,
|
|
1003
|
+
and a file of `@angular/forms` comes out as `node_modules/.pnpm/k8-fastbuild-ST-…/bin/packages/forms/…`
|
|
1004
|
+
(`bin/src/material/…` for the components repository). Read as a path, that is a package called
|
|
1005
|
+
`.pnpm`; it is read as `@angular/forms`, and never as a second installed copy of it.
|
|
849
1006
|
|
|
850
1007
|
The preload lists are the one place a bundler's own behaviour changes a figure. Vite does not wait for
|
|
851
1008
|
a lazy chunk to arrive and be parsed before fetching what it imports — it bakes the list into the call
|
|
852
1009
|
and asks for the whole set at once. Angular does not. Without reading those lists, every screen of a
|
|
853
1010
|
Vite application would be counted one round trip deeper than it is.
|
|
854
1011
|
|
|
1012
|
+
### webpack's `stats.json`
|
|
1013
|
+
|
|
1014
|
+
Refused on purpose until 09/10/2026, with "Statoscope does it better". It is also what nearly every
|
|
1015
|
+
application written before 2020 can produce — Angular up to 16, Create React App, Vue CLI, Gatsby,
|
|
1016
|
+
Nuxt 2, Rspack — and their folders cannot be read, so for them the refusal was the whole answer.
|
|
1017
|
+
The stats file has the three things the metafile has, in another shape, and
|
|
1018
|
+
`core/intake/webpack-stats.ts` translates it:
|
|
1019
|
+
|
|
1020
|
+
| webpack | metafile |
|
|
1021
|
+
| ------------------------------------ | ----------------------------------------------------------- |
|
|
1022
|
+
| `modules[]` and `chunks[].modules[]` | `inputs`, with the edges taken from each module's `reasons` |
|
|
1023
|
+
| `chunks[].files` and `assets[].size` | `outputs`, one per file the browser downloads |
|
|
1024
|
+
| `entrypoints[].chunks` | static edges: the files an entry starts with |
|
|
1025
|
+
| `chunks[].origins` | lazy edges: which file asked for the chunk, and where |
|
|
1026
|
+
|
|
1027
|
+
- **A lazy chunk group is one screen.** Every chunk sharing an origin — the `import()` at one place in
|
|
1028
|
+
one file — is fetched at once by `__webpack_require__.e`. The one holding the module asked for is
|
|
1029
|
+
the lazy entry; the others (the vendors `splitChunks` moved out, a chunk two routes share) travel
|
|
1030
|
+
with it, statically, and in the same round trip (`fetchedWith`, which plays the part of Vite's
|
|
1031
|
+
preload list).
|
|
1032
|
+
- **⚠️ A module's `size` is its source, before minification.** An Angular 8 main chunk is 2.9 MB of
|
|
1033
|
+
modules in a file of 560 kB. The per-file weights are those sizes shared out in proportion to what
|
|
1034
|
+
the file weighs, so they add up to the file: an estimate, since minification does not shrink every
|
|
1035
|
+
file by the same factor. A source map in the folder replaces it with a measurement, as for any build.
|
|
1036
|
+
- **A concatenated module is taken apart.** webpack 4 writes "`./src/main.ts + 20 modules` imports
|
|
1037
|
+
rxjs", and taken at its word `main.ts` was a barrel of 26 re-exports holding 546 kB. The file that
|
|
1038
|
+
wrote the import is found by what it wrote — a relative path that resolves, a package named in its
|
|
1039
|
+
source — or by the module webpack says imported it first; with none of them the edge is left out.
|
|
1040
|
+
webpack 5 names the file itself (`resolvedModule`).
|
|
1041
|
+
- **What is no file is left out**: `multi …` entries, `external "React"`, ignored modules. webpack's
|
|
1042
|
+
own runtime is filed under `node_modules/webpack`, and the loaders in front of a name, the query of
|
|
1043
|
+
a Vue component's part and the `./` are dropped, so the names are the metafile's.
|
|
1044
|
+
- **The stats file sits inside the folder it describes** when webpack writes it there — Angular 8's
|
|
1045
|
+
`dist/stats-es2015.json`, Create React App's `build/bundle-stats.json`, Vue CLI's `dist/report.json`
|
|
1046
|
+
— and the command and the page both read it with that folder, so the figures stay compressed.
|
|
1047
|
+
|
|
1048
|
+
`fixtures/webpack4-app` and `fixtures/webpack5-app` hold up the translation: the application of
|
|
1049
|
+
`vite-app` comes out with the same three screens and the same deferred widget.
|
|
1050
|
+
|
|
1051
|
+
### Yours or theirs
|
|
1052
|
+
|
|
1053
|
+
Every rule that tells your code from a dependency asks one function (`core/format/ownership.ts`),
|
|
1054
|
+
where there used to be a dozen `includes('node_modules')`. A file is a dependency when it sits under
|
|
1055
|
+
`node_modules/`, with one convention read: Sapper keeps an application's own modules in
|
|
1056
|
+
`src/node_modules/` so they import by name, and the RealWorld app's `api.js` and `utils.js` came out
|
|
1057
|
+
as packages, Sapper's runtime as a package called `@sapper/app.mjs`. `build.own` and
|
|
1058
|
+
`build.dependencies` of `loadline.json` say the rest — a monorepo's `packages/ui` as the package `ui`,
|
|
1059
|
+
code of yours that a tool put under `node_modules/`. Like the language of the figures, it is set once
|
|
1060
|
+
from outside, by the command when it reads the file and by the page when one is dropped, because a
|
|
1061
|
+
path is named from everywhere in the report.
|
|
1062
|
+
|
|
1063
|
+
### What wrote the build
|
|
1064
|
+
|
|
1065
|
+
The advice names a setting, and a setting belongs to a tool: an Ember build was told to write
|
|
1066
|
+
`sourcemap: true` in a Vite config it does not have, and that its `console.log` calls might be
|
|
1067
|
+
Angular's. The tool is in what is read already (`core/analysis/tool.ts`): the reader that translated a
|
|
1068
|
+
webpack stats file or found Stencil's list of components says so (`Metafile.builtBy`), the page names
|
|
1069
|
+
Sapper, Nuxt, SvelteKit, Ember and Polymer, a chunk names Vite (its preload helper) and Angular (the
|
|
1070
|
+
`ng-version` its runtime sets), and with source maps the packages name the framework. A metafile
|
|
1071
|
+
nobody else wrote is esbuild's. The command prints it in its lead and in `builtWith`, and the advice
|
|
1072
|
+
on source maps, on splitting the dependencies out and on whose a `console.log` is uses it; when
|
|
1073
|
+
nothing says, the advice names Vite and Angular, as before.
|
|
1074
|
+
|
|
855
1075
|
### What is not a metafile
|
|
856
1076
|
|
|
857
|
-
|
|
858
|
-
about
|
|
1077
|
+
Two files are commonly believed to be "the stats of my build". "Could not read it" would be a lie
|
|
1078
|
+
about both: the file is fine, it is another format, and Loadline says which.
|
|
859
1079
|
|
|
860
|
-
| What | Where it comes from
|
|
861
|
-
| -------------------------- |
|
|
862
|
-
|
|
|
863
|
-
|
|
|
864
|
-
|
|
1080
|
+
| What | Where it comes from | Why it is not read |
|
|
1081
|
+
| -------------------------- | ---------------------- | ------------------------------------------------------------- |
|
|
1082
|
+
| Vite `manifest.json` | `build.manifest: true` | Not needed: the folder itself says the same thing, and better |
|
|
1083
|
+
| `rollup-plugin-visualizer` | its `--json` output | A drawn tree, not the build's own record |
|
|
1084
|
+
|
|
1085
|
+
A webpack `stats.json` written with `chunks` or `assets` off is refused too: it has nothing to analyse.
|
|
865
1086
|
|
|
866
1087
|
The Vite manifest was the obvious thing to read and it aged badly in a few months: with Rolldown as
|
|
867
1088
|
the default it is a compatibility layer somebody has to switch on, while the folder is always there
|
|
@@ -869,7 +1090,7 @@ and needs nobody to maintain a format.
|
|
|
869
1090
|
|
|
870
1091
|
### Two build shapes that are not a plain SPA
|
|
871
1092
|
|
|
872
|
-
Both were analysed wrongly at first, and both are becoming more common (`core/analysis/entries.ts`).
|
|
1093
|
+
Both were analysed wrongly at first, and both are becoming more common (`core/analysis/screens/entries.ts`).
|
|
873
1094
|
|
|
874
1095
|
**Server-side rendering writes one metafile with both sides in it.** Nobody downloads the server
|
|
875
1096
|
bundle and it is usually the bigger of the two, so "the entry that reaches the most" would pick it and
|
|
@@ -943,6 +1164,28 @@ An answer nobody recognises becomes "unanswered" plus a line to print, the same
|
|
|
943
1164
|
no reason: an answer is the only thing in this file that can move a colour, so it is the one mistake
|
|
944
1165
|
that would otherwise change a verdict silently.
|
|
945
1166
|
|
|
1167
|
+
### One file shared by many repositories
|
|
1168
|
+
|
|
1169
|
+
`extends` follows what every tool with shared configuration agrees on — semantic-release, ESLint,
|
|
1170
|
+
Renovate, TypeScript, Biome, Stylelint: left to right, the last one wins, the file that extends goes
|
|
1171
|
+
last, and a path is read from the file that writes it. Where they disagree is lists, and the choice
|
|
1172
|
+
here is **lists add up**, with Biome and webpack, against TypeScript, where a list in the child
|
|
1173
|
+
replaces the base's whole. "I set `include` and lost the base's" is the best-known surprise of
|
|
1174
|
+
`tsconfig.json`, and the lists of this file — packages, acceptances, forbidden rules — are things a
|
|
1175
|
+
repository adds to. Renovate decides per option, which is the one shape nobody can predict without
|
|
1176
|
+
reading its source. Taking something of the base away, which adding cannot do, already has a way that
|
|
1177
|
+
carries a reason: an acceptance.
|
|
1178
|
+
|
|
1179
|
+
Three things were left out, each for a reason. **No URLs**: a base fetched at run time needs network
|
|
1180
|
+
in CI and can change under a build without a commit; a package is pinned by the lock file. **No name
|
|
1181
|
+
prefix** (`eslint-config-`, `commitlint-config-`): one more rule to learn, and a name that is not the
|
|
1182
|
+
one in `package.json`. **No plugins**: see 3.24.
|
|
1183
|
+
|
|
1184
|
+
The page has no disk, so it cannot follow `extends`. It says so above the report and applies only
|
|
1185
|
+
what the dropped file says; `--print-config` writes the joined file for it. Two keys do not join:
|
|
1186
|
+
`situation`, which is one team's answers with its name on them, and `mode`, which a file cannot change
|
|
1187
|
+
under a base that wrote its sizes in another unit.
|
|
1188
|
+
|
|
946
1189
|
---
|
|
947
1190
|
|
|
948
1191
|
## 6. Design decisions
|
|
@@ -1016,6 +1259,23 @@ next to its module: `analysis.ts` computes, `analysis.types.ts` says what comes
|
|
|
1016
1259
|
reading order — a module opens on its first function instead of two hundred lines of declarations.
|
|
1017
1260
|
Types that never leave their file stay in it, and so does the input contract of a component.
|
|
1018
1261
|
|
|
1262
|
+
**No two folders of `core/` import each other in a loop.** Loadline reports import cycles between
|
|
1263
|
+
folders, and run on its own build it found one: seven folders — `intake`, `analysis`, `assets`,
|
|
1264
|
+
`caching`, `baseline`, `findings`, `config` — each reaching the others. Two small readers kept the loop
|
|
1265
|
+
closed: `index-html.ts` and `route-table.ts` lived in `intake/`, which reads a dropped folder with
|
|
1266
|
+
everything else, while `assets/` and `analysis/` needed them. They import nothing of the analysis, so
|
|
1267
|
+
they moved to `core/build-text/` — what a build writes in its own text, read by every layer above it —
|
|
1268
|
+
and the loop opened. The last edge, `situation/` borrowing three sentences from `config/`, went the
|
|
1269
|
+
same way: those sentences live next to the code that says them.
|
|
1270
|
+
|
|
1271
|
+
**No folder holds more than twenty files.** Past that a folder is scrolled rather than read, so the
|
|
1272
|
+
big ones are split by what their files are about: `core/analysis/` into `graph/`, `screens/`,
|
|
1273
|
+
`sourcemap/` and `views/`; `core/findings/` into the signals read from the bundle (`bundle/`), from the
|
|
1274
|
+
rest of the build folder (`folder/`) and from what somebody hands over (`supplied/`), with their words
|
|
1275
|
+
in `text/`; `cli/` into `read/`, `render/` and `text/`. Four modules sharing a prefix get a folder of
|
|
1276
|
+
that name for the same reason. `tooling/check-folders.mjs` holds both lines, and the exceptions it
|
|
1277
|
+
allows say why.
|
|
1278
|
+
|
|
1019
1279
|
**Three path aliases, one per layer**, declared in `tsconfig.json`: `@core/*`, `@shared/*` and
|
|
1020
1280
|
`@state/*`, for imports that would otherwise climb. Siblings and one level up stay relative.
|
|
1021
1281
|
`features/` has no alias on purpose: inside a screen everything is a sibling, and an alias there would
|
|
@@ -1060,10 +1320,11 @@ question none of them answers, and leaves out things several of them do well.
|
|
|
1060
1320
|
- **Line-level duplication across chunks** (Bundle Buddy). Loadline works at file and package level.
|
|
1061
1321
|
Not started on purpose: comparing everything with everything is expensive inside the browser, and
|
|
1062
1322
|
the typical finding — a copied utility — usually weighs little.
|
|
1063
|
-
- **Webpack** (Statoscope, webpack-bundle-analyzer, bundle-stats). Loadline reads
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1323
|
+
- **Webpack's own detail** (Statoscope, webpack-bundle-analyzer, bundle-stats). Loadline reads
|
|
1324
|
+
webpack's `stats.json` as a metafile since 09/10/2026, so its questions — the first load, the screens,
|
|
1325
|
+
what each one adds — are answered for webpack builds too. What it does not read is everything
|
|
1326
|
+
webpack-specific those tools show: module ids, chunk-group internals, the minified size of each
|
|
1327
|
+
module measured in the bundle rather than shared out. Next.js with Turbopack writes no stats file.
|
|
1067
1328
|
|
|
1068
1329
|
### 7.3 One finding worth keeping
|
|
1069
1330
|
|