@bymaksym/loadline 0.1.0 → 1.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/README.md +272 -45
- package/dist/cli/cli/args.js +97 -116
- package/dist/cli/cli/gates.js +80 -14
- package/dist/cli/cli/main.js +275 -31
- package/dist/cli/cli/memory.js +114 -0
- package/dist/cli/cli/read/declared.js +52 -0
- package/dist/cli/cli/read/locate.js +214 -0
- package/dist/cli/cli/{read-build.js → read/read-build.js} +156 -87
- package/dist/cli/cli/read/read-config.js +120 -0
- package/dist/cli/cli/render/html-report.js +111 -0
- 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} +26 -10
- package/dist/cli/cli/{render-markdown.js → render/render-markdown.js} +6 -6
- package/dist/cli/cli/{render-pr.js → render/render-pr.js} +37 -15
- package/dist/cli/cli/{render-sarif.js → render/render-sarif.js} +11 -6
- package/dist/cli/cli/{render-text.js → render/render-text.js} +169 -127
- package/dist/cli/cli/render/terminal.js +55 -0
- package/dist/cli/cli/report.js +76 -29
- package/dist/cli/cli/self-check.js +19 -23
- package/dist/cli/cli/since-last.js +45 -0
- 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 +68 -24
- package/dist/cli/src/app/core/analysis/{barrels.js → graph/barrels.js} +10 -3
- 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 +21 -7
- 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} +87 -11
- 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} +13 -7
- package/dist/cli/src/app/core/analysis/tool.js +83 -0
- package/dist/cli/src/app/core/assets/assets.js +137 -16
- package/dist/cli/src/app/core/baseline/baseline.js +0 -0
- package/dist/cli/src/app/core/{intake → build-text}/index-html.js +234 -29
- 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 +123 -45
- 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 +141 -23
- package/dist/cli/src/app/core/deps/pins.js +63 -0
- package/dist/cli/src/app/core/export/summary.js +54 -12
- package/dist/cli/src/app/core/findings/actions.js +65 -6
- package/dist/cli/src/app/core/findings/bundle/boot-single.js +76 -0
- package/dist/cli/src/app/core/findings/bundle/dupes.js +68 -0
- package/dist/cli/src/app/core/findings/{graph.js → bundle/graph.js} +32 -20
- 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} +30 -18
- package/dist/cli/src/app/core/findings/compose.js +6 -1
- package/dist/cli/src/app/core/findings/effort.js +4 -0
- package/dist/cli/src/app/core/findings/finding.types.js +2 -0
- package/dist/cli/src/app/core/findings/findings.js +68 -55
- package/dist/cli/src/app/core/findings/{assets.js → folder/assets.js} +65 -16
- package/dist/cli/src/app/core/findings/{caching.js → folder/caching.js} +17 -10
- 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} +37 -13
- 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/text/finding-html.js +33 -0
- package/dist/cli/src/app/core/findings/{finding-text.js → text/finding-text.js} +307 -103
- package/dist/cli/src/app/core/findings/text/tool-advice.js +97 -0
- package/dist/cli/src/app/core/format/format.utils.js +172 -18
- package/dist/cli/src/app/core/format/ownership.js +93 -0
- package/dist/cli/src/app/core/i18n/en.js +180 -61
- package/dist/cli/src/app/core/i18n/es.js +192 -68
- package/dist/cli/src/app/core/intake/bundle-graph.js +285 -46
- package/dist/cli/src/app/core/intake/dist-files.js +87 -16
- package/dist/cli/src/app/core/intake/embedded.js +56 -0
- 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/budget-advice.js +14 -10
- package/dist/cli/src/app/core/project/project-context.js +89 -19
- package/dist/cli/src/app/core/project/project-name.js +36 -0
- package/dist/cli/src/app/core/scan/scan.js +116 -39
- package/dist/cli/src/app/core/scan/secrets.js +0 -0
- package/dist/cli/src/app/core/situation/situation-text.js +23 -0
- package/dist/cli/src/app/core/situation/situation.js +9 -8
- 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/dist/cli/src/app/state/report-messages.utils.js +1 -4
- package/docs/CONFIG-REFERENCE.md +230 -0
- package/docs/CONFIG.md +511 -0
- package/docs/HOW-IT-WORKS.md +286 -25
- package/loadline.html +26 -24
- package/loadline.schema.json +1209 -0
- package/package.json +71 -35
- package/dist/cli/cli/text.js +0 -180
- package/dist/cli/src/app/core/findings/finding-html.js +0 -13
- /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/CONFIG.md
ADDED
|
@@ -0,0 +1,511 @@
|
|
|
1
|
+
# Configuring Loadline — `loadline.json`
|
|
2
|
+
|
|
3
|
+
One optional file, committed next to your code, so the page and the command judge the build the
|
|
4
|
+
same way. Without it everything works with the recommended values and nothing ever fails.
|
|
5
|
+
|
|
6
|
+
**Find what you want to do:**
|
|
7
|
+
|
|
8
|
+
| I want to… | Use | Jump |
|
|
9
|
+
| --------------------------------------------------------- | ------------------------------------- | --------------------------------------------------- |
|
|
10
|
+
| Make CI fail when the first load is too big | `gates.maxBoot` | [Fail the build](#fail-the-build-on-size) |
|
|
11
|
+
| Allow one heavy screen more than the others | `gates.screens` | [One limit per screen](#one-limit-per-screen) |
|
|
12
|
+
| Fail when a pull request makes things grow | `gates.maxGrowth` + `--baseline` | [Fail on growth](#fail-on-growth) |
|
|
13
|
+
| Stop new packages sneaking into the first load | `packages` + `gates.failOnNewPackage` | [Guard the bootstrap](#guard-the-bootstrap) |
|
|
14
|
+
| Fail on serious signals | `gates.failOn` | [Fail on signals](#fail-on-signals) |
|
|
15
|
+
| Fail on one signal always, whatever its severity | `gates.failOnSignals` | [Fail on signals](#fail-on-signals) |
|
|
16
|
+
| Never ship a package, or never in the first load | `forbidden` | [Forbid something](#forbid-something) |
|
|
17
|
+
| Share one file between many repositories | `extends` | [Share the configuration](#share-the-configuration) |
|
|
18
|
+
| Change what counts as good, fair or bad | `criteria` | [Thresholds](#change-the-thresholds) |
|
|
19
|
+
| Live with a signal for now, without hiding it forever | `accepted` | [Accept a signal](#accept-a-signal) |
|
|
20
|
+
| Tell Loadline how the team releases and who the users are | `situation` | [The situation](#answer-the-five-questions) |
|
|
21
|
+
| See every key, its unit and its recommended value | — | [Reference](CONFIG-REFERENCE.md) |
|
|
22
|
+
|
|
23
|
+
## Start in thirty seconds
|
|
24
|
+
|
|
25
|
+
Create `loadline.json` at the root of the project — where you run `loadline` from:
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"$schema": "https://unpkg.com/@bymaksym/loadline/loadline.schema.json",
|
|
30
|
+
"tool": "loadline",
|
|
31
|
+
"version": 1,
|
|
32
|
+
"gates": { "maxBoot": "350kB" }
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The first line is what makes the file easy: VS Code, WebStorm and most editors read the schema it
|
|
37
|
+
points at and then **complete every key, explain it on hover, list the allowed values and underline
|
|
38
|
+
a typo** as you type. `tool` and `version` are always those two values.
|
|
39
|
+
|
|
40
|
+
The command finds `loadline.json` in the working directory on its own; `--config <file>` points at
|
|
41
|
+
another one. The page reads it too when you drop it in with the build.
|
|
42
|
+
|
|
43
|
+
## How the file is used
|
|
44
|
+
|
|
45
|
+
Each block does one job. Only `gates` can make the command fail.
|
|
46
|
+
|
|
47
|
+
```mermaid
|
|
48
|
+
flowchart LR
|
|
49
|
+
build[(Your build)] --> analysis[Analysis]
|
|
50
|
+
criteria["criteria<br/>thresholds"] --> analysis
|
|
51
|
+
situation["situation<br/>five answers"] --> analysis
|
|
52
|
+
analysis --> signals[Figures, colours<br/>and signals]
|
|
53
|
+
signals --> accepted{"accepted?"}
|
|
54
|
+
accepted -- "covered, in date,<br/>not grown" --> aside["Listed under<br/>'Accepted'"]
|
|
55
|
+
accepted -- otherwise --> report[The report]
|
|
56
|
+
report --> gates{"gates<br/>+ packages"}
|
|
57
|
+
gates -- "a limit is broken" --> fail["exit 1<br/>pipeline fails"]
|
|
58
|
+
gates -- "all under" --> pass["exit 0"]
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- **`criteria`** colour the figures and decide when a signal fires. They never fail anything.
|
|
62
|
+
- **`situation`** answers what no build can say — how often you release, who comes back. An answer
|
|
63
|
+
can make a signal more serious, never less.
|
|
64
|
+
- **`accepted`** sets a signal aside with a reason and an expiry. It is still listed.
|
|
65
|
+
- **`gates`** turn figures and signals into an exit code. Without gates the command only reports.
|
|
66
|
+
|
|
67
|
+
### Who wins
|
|
68
|
+
|
|
69
|
+
A flag typed on the command line wins over the file, the file wins over what it
|
|
70
|
+
[extends](#share-the-configuration), and that wins over the recommended values. The page edits the
|
|
71
|
+
same thresholds and can export them as a block of this file.
|
|
72
|
+
|
|
73
|
+
```mermaid
|
|
74
|
+
flowchart LR
|
|
75
|
+
rec["Recommended values"] -->|overridden by| base["What it extends<br/>@acme/loadline-config"]
|
|
76
|
+
base -->|overridden by| file["loadline.json"]
|
|
77
|
+
file -->|overridden by| flags["--criteria file<br/>--max-boot, --fail-on…"]
|
|
78
|
+
flags --> used(["What this run uses"])
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Sizes and shares
|
|
82
|
+
|
|
83
|
+
Write sizes the way you read them, anywhere in the file:
|
|
84
|
+
|
|
85
|
+
| You write | It means |
|
|
86
|
+
| -------------------- | ---------------------------------------------- |
|
|
87
|
+
| `"350kB"`, `"1.5MB"` | 350 × 1024 bytes, 1.5 × 1024 × 1024 bytes |
|
|
88
|
+
| `358400` | Bytes |
|
|
89
|
+
| `"25%"` or `0.25` | A share, for the criteria that are shares |
|
|
90
|
+
| `350`, `"350"` | **Refused**: 350 bytes is never what was meant |
|
|
91
|
+
|
|
92
|
+
Sizes are in the unit of the report — gzip when the build folder is there, raw otherwise. Set
|
|
93
|
+
`mode` to the unit you wrote them in: the command then reports in that unit (unless `--mode` says
|
|
94
|
+
otherwise), so a limit written in gzip is never checked against raw bytes. A `mode` the folder cannot
|
|
95
|
+
give — `brotli` with no `.br` files — stops the run with exit code 2.
|
|
96
|
+
|
|
97
|
+
### When something is wrong in the file
|
|
98
|
+
|
|
99
|
+
Nothing in the file is ignored in silence. A key that does not exist or a signal with no reason is
|
|
100
|
+
**printed** when the command runs, and the rest of the file still applies.
|
|
101
|
+
|
|
102
|
+
A mistake in `gates` is different: it **stops the run with exit code 2**, as the same mistake typed as
|
|
103
|
+
a flag does. A gate that cannot be read would otherwise not run, and a pipeline guarded by a gate
|
|
104
|
+
that does not run passes:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
loadline.json: "gates.maxBot" is not a gate, so it guards nothing. "gates.maxScreen" is 350, which
|
|
108
|
+
would be 350 bytes. Write "350kB", or "350B" if bytes are meant. That gate cannot run.
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
A file passed with `--config` that is not a `loadline.json` stops the run the same way.
|
|
112
|
+
|
|
113
|
+
## Fail the build on size
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
"gates": {
|
|
117
|
+
"maxBoot": "350kB",
|
|
118
|
+
"maxScreen": "600kB",
|
|
119
|
+
"maxOwn": "150kB"
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
| Gate | Measures |
|
|
124
|
+
| ----------- | --------------------------------------------------------- |
|
|
125
|
+
| `maxBoot` | What downloads before anything appears: the bootstrap |
|
|
126
|
+
| `maxScreen` | Everything someone landing directly on a screen downloads |
|
|
127
|
+
| `maxOwn` | The part only that screen loads |
|
|
128
|
+
|
|
129
|
+
```text
|
|
130
|
+
what a screen downloads (maxScreen)
|
|
131
|
+
┌──────────────────────────────┬─────────────────┬───────────────┐
|
|
132
|
+
│ bootstrap (maxBoot) │ shared chunks │ own (maxOwn) │
|
|
133
|
+
└──────────────────────────────┴─────────────────┴───────────────┘
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The same gates exist as flags (`--max-boot 350kB`), which win over the file.
|
|
137
|
+
|
|
138
|
+
## One limit per screen
|
|
139
|
+
|
|
140
|
+
A map or an editor is heavy on purpose. Give it its own limit instead of loosening `maxScreen` for
|
|
141
|
+
every screen:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
"gates": {
|
|
145
|
+
"maxScreen": "500kB",
|
|
146
|
+
"screens": {
|
|
147
|
+
"map": "900kB",
|
|
148
|
+
"src/app/editor/editor.page.ts": "750kB"
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
A screen is named as the report names it (the first column of the screens table) or by its source
|
|
154
|
+
file, which survives a rename of the route. A name that matches no screen is printed with the names
|
|
155
|
+
that do exist, so a renamed route cannot leave a limit guarding nothing.
|
|
156
|
+
|
|
157
|
+
## Fail on growth
|
|
158
|
+
|
|
159
|
+
```json
|
|
160
|
+
"gates": { "maxGrowth": "20kB", "maxGrowthPct": "5%" }
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Growth needs something to grow from: pass the previous build with `--baseline`. The
|
|
164
|
+
[CI recipes in the README](../README.md#in-ci) keep the last build of `main` for exactly this. Each
|
|
165
|
+
screen is judged on what it adds beyond the bootstrap, and the bootstrap on its own, so one shared
|
|
166
|
+
change does not fail every screen at once.
|
|
167
|
+
|
|
168
|
+
## Guard the bootstrap
|
|
169
|
+
|
|
170
|
+
Bundles rarely grow all at once; they grow one `npm install` at a time.
|
|
171
|
+
|
|
172
|
+
```json
|
|
173
|
+
"packages": ["@angular/core", "@angular/common", "@angular/router", "rxjs"],
|
|
174
|
+
"gates": { "failOnNewPackage": true }
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Any package in the first load that is not on the list fails the run, and adding one becomes a line
|
|
178
|
+
somebody reviews. Without `packages`, the gate compares against `--baseline` instead.
|
|
179
|
+
|
|
180
|
+
To find out why a package is there and where to cut it out:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
npx @bymaksym/loadline dist/app/browser --why @microsoft/teams-js
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Fail on signals
|
|
187
|
+
|
|
188
|
+
```json
|
|
189
|
+
"gates": { "failOn": "high" }
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`"high"` fails on the most serious signals only, `"mid"` on those and the medium ones, `"none"`
|
|
193
|
+
never. Before switching to `"mid"`, [accept](#accept-a-signal) the medium signals you have decided
|
|
194
|
+
to live with, or the first run will fail on them.
|
|
195
|
+
|
|
196
|
+
A level is the wrong tool for "this one, always". To fail on particular signals whatever their
|
|
197
|
+
severity, name them:
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
"gates": { "failOn": "none", "failOnSignals": ["forbidden", "secrets", "vulnerable"] }
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Each one that is raised is its own line in the log, so it says which signal stopped the run. The
|
|
204
|
+
names are the `kind` of each signal, listed in the [reference](CONFIG-REFERENCE.md#signals-kind-can-name).
|
|
205
|
+
Accepted signals do not count, here or in `failOn`. A name that is not a signal stops the run with
|
|
206
|
+
exit code 2: a typo there would be a gate guarding nothing.
|
|
207
|
+
|
|
208
|
+
## Forbid something
|
|
209
|
+
|
|
210
|
+
Every team has a rule like "no moment, we use date-fns" or "the admin area is lazy". Write it down
|
|
211
|
+
and Loadline checks it on every build:
|
|
212
|
+
|
|
213
|
+
```json
|
|
214
|
+
"forbidden": [
|
|
215
|
+
{ "package": "moment", "why": "We use date-fns. moment ships every language." },
|
|
216
|
+
{ "package": "lodash", "in": "bootstrap", "why": "Use lodash-es, and only in lazy screens." },
|
|
217
|
+
{ "path": "src/app/admin/*", "in": "bootstrap", "why": "Admin is lazy: someone imported it from the shell." }
|
|
218
|
+
]
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
| Field | Required | What it is |
|
|
222
|
+
| --------- | :--------: | ------------------------------------------------------------------------------------------------------------------------- |
|
|
223
|
+
| `package` | one of the | A package name. `*` stands for any text: `"@aws-sdk/*"` |
|
|
224
|
+
| `path` | two | Files of your project, with `*` as in [`build`](#when-it-reads-your-build-wrong): `"src/app/admin/*"` |
|
|
225
|
+
| `in` | | `"anywhere"`, the default: in no file of the build. `"bootstrap"`: not in the first load, a lazy screen may still load it |
|
|
226
|
+
| `why` | yes | Why not, and what to use instead. It is the first thing on the signal |
|
|
227
|
+
|
|
228
|
+
Each rule that matches raises a **`forbidden`** signal of high severity. It says what matched, how
|
|
229
|
+
much it weighs, and the chain of imports that brings it in — the last file of yours in that chain is
|
|
230
|
+
the one to edit.
|
|
231
|
+
|
|
232
|
+
```mermaid
|
|
233
|
+
flowchart LR
|
|
234
|
+
rule["forbidden rule"] --> match{"matches a file<br/>of the build?"}
|
|
235
|
+
match -- no --> quiet[Nothing]
|
|
236
|
+
match -- yes --> signal["'forbidden' signal<br/>high, with the why"]
|
|
237
|
+
signal --> acc{"in accepted?"}
|
|
238
|
+
acc -- "yes, in date" --> aside[Listed under 'Accepted']
|
|
239
|
+
acc -- no --> gate{"failOn: high or<br/>failOnSignals?"}
|
|
240
|
+
gate -- yes --> fail["exit 1"]
|
|
241
|
+
gate -- no --> shown[In the report]
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
It is an ordinary signal on purpose, so nothing new has to be learnt to work with it:
|
|
245
|
+
|
|
246
|
+
- **To fail the build on it**, use `"failOn": "high"` or `"failOnSignals": ["forbidden"]`.
|
|
247
|
+
- **For an exception in one repository**, [accept](#accept-a-signal) it with a reason and a date. The
|
|
248
|
+
`key` is the rule as you wrote it: `{ "kind": "forbidden", "key": "moment", "why": "…", "until": "…" }`.
|
|
249
|
+
- **When the rule no longer holds**, remove it from the list, in a review.
|
|
250
|
+
|
|
251
|
+
`packages` is the closed version of the same idea: everything not on that list fails. `forbidden`
|
|
252
|
+
is the open one: only what you name fails. A rule that cannot be read — no `why`, both `package` and
|
|
253
|
+
`path`, an `in` that is not one of the two — stops the run with exit code 2, like a broken gate.
|
|
254
|
+
|
|
255
|
+
## Share the configuration
|
|
256
|
+
|
|
257
|
+
With twenty repositories, write the rules once and have each repository extend them:
|
|
258
|
+
|
|
259
|
+
```json
|
|
260
|
+
{
|
|
261
|
+
"$schema": "https://unpkg.com/@bymaksym/loadline/loadline.schema.json",
|
|
262
|
+
"tool": "loadline",
|
|
263
|
+
"version": 1,
|
|
264
|
+
"extends": "@acme/loadline-config",
|
|
265
|
+
"gates": { "screens": { "map": "900kB" } }
|
|
266
|
+
}
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Five rules are all there is to it:
|
|
270
|
+
|
|
271
|
+
1. **What you write.** A path (`"./base.loadline.json"`) or a package (`"@acme/loadline-config"`,
|
|
272
|
+
which reads that package's `loadline.json`). One name, or a list of them. A path is read from the
|
|
273
|
+
folder of the file that writes it, so a base that extends another base works from any repository.
|
|
274
|
+
2. **Order.** First what you extend, then your file; in a list, left to right. **The last one wins.**
|
|
275
|
+
3. **How they join.** Objects — `criteria`, `gates`, `build` — key by key. **Lists add up**:
|
|
276
|
+
`packages`, `accepted`, `forbidden`, `failOnSignals`, `build.entries`, `build.ignore`.
|
|
277
|
+
4. **What is not inherited.** `situation`: those are one team's answers, with its name on them. And a
|
|
278
|
+
file cannot change the `mode` of what it extends: every inherited size would be read in the wrong
|
|
279
|
+
unit.
|
|
280
|
+
5. **What stops the run** with exit code 2: a name that is not found, a file that ends up extending
|
|
281
|
+
itself, a broken gate in any of the files, a `mode` that differs.
|
|
282
|
+
|
|
283
|
+
Lists add up because they are things a repository adds to: the packages the base allows, plus one;
|
|
284
|
+
the base's acceptances, plus its own. What adding cannot do is take something of the base away, and
|
|
285
|
+
the file already has the way to do that with a reason attached: an entry in `accepted`.
|
|
286
|
+
|
|
287
|
+
### See what it ended up as
|
|
288
|
+
|
|
289
|
+
```bash
|
|
290
|
+
npx @bymaksym/loadline --print-config
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
It prints the `loadline.json` the run uses, with everything it extends joined in — sizes in bytes,
|
|
294
|
+
which is what they are once read — and, on stderr, which files it came from. It needs no build:
|
|
295
|
+
|
|
296
|
+
```text
|
|
297
|
+
thresholds and accepted signals from loadline.json ← node_modules/@acme/loadline-config/loadline.json
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
**The page cannot follow `extends`**: it has no disk to look on. When the file you drop on it extends
|
|
301
|
+
others, the bar above the report says so, and the page applies only what that file says itself. Drop
|
|
302
|
+
what `--print-config` prints instead, and the page judges the build exactly as the command does.
|
|
303
|
+
When the page exports its thresholds from a file that extends a base, it writes only the ones that
|
|
304
|
+
were changed, so the export does not override every threshold of the base.
|
|
305
|
+
|
|
306
|
+
### Publish the shared file
|
|
307
|
+
|
|
308
|
+
A package with the file at its root, and nothing else:
|
|
309
|
+
|
|
310
|
+
```text
|
|
311
|
+
acme-loadline-config/
|
|
312
|
+
├── package.json
|
|
313
|
+
└── loadline.json
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
```json
|
|
317
|
+
{
|
|
318
|
+
"name": "@acme/loadline-config",
|
|
319
|
+
"version": "1.0.0",
|
|
320
|
+
"files": ["loadline.json"]
|
|
321
|
+
}
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
If the package has an `"exports"` field, list the file in it — `"./loadline.json": "./loadline.json"`
|
|
325
|
+
— or Node will not let anything read it. Install it as a development dependency of each repository.
|
|
326
|
+
The base then moves only when somebody updates that dependency, in a commit, with the version in the
|
|
327
|
+
lock file: a shared threshold never changes under a build without a review.
|
|
328
|
+
|
|
329
|
+
Without a package, a path works too: `"extends": "../platform/loadline.json"` in a monorepo.
|
|
330
|
+
|
|
331
|
+
## Change the thresholds
|
|
332
|
+
|
|
333
|
+
Every rated figure has two thresholds. Up to the first it is **good**, up to the second **fair**,
|
|
334
|
+
above it **bad**:
|
|
335
|
+
|
|
336
|
+
```text
|
|
337
|
+
bootstrap size
|
|
338
|
+
0 ────────────────── bootOk ──────────────────── bootBad ──────────────────▶
|
|
339
|
+
good fair bad
|
|
340
|
+
170kB (gzip) 350kB (gzip)
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
```json
|
|
344
|
+
"mode": "gzip",
|
|
345
|
+
"criteria": {
|
|
346
|
+
"bootOk": "150kB",
|
|
347
|
+
"bootBad": "300kB",
|
|
348
|
+
"sharedRatio": "50%"
|
|
349
|
+
}
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
Anything you leave out keeps its recommended value. There are about forty thresholds; the
|
|
353
|
+
[reference](CONFIG-REFERENCE.md#criteria) lists each one with its recommended value in gzip,
|
|
354
|
+
brotli and raw.
|
|
355
|
+
|
|
356
|
+
The easiest way to tune them is the page: open the criteria panel, move the values until the report
|
|
357
|
+
looks right, and export them. The file you get is a `loadline.json` with only `mode` and `criteria`
|
|
358
|
+
— use it as it is, merge the block into yours, or pass it with `--criteria`.
|
|
359
|
+
|
|
360
|
+
## Accept a signal
|
|
361
|
+
|
|
362
|
+
When the team decides to live with something, write it down instead of switching the check off:
|
|
363
|
+
|
|
364
|
+
```json
|
|
365
|
+
"accepted": [
|
|
366
|
+
{
|
|
367
|
+
"kind": "dupes",
|
|
368
|
+
"key": "date-fns",
|
|
369
|
+
"why": "Two versions until the calendar library releases 4.x",
|
|
370
|
+
"who": "@maks",
|
|
371
|
+
"until": "2026-12-01",
|
|
372
|
+
"bytes": "14kB"
|
|
373
|
+
}
|
|
374
|
+
]
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
```mermaid
|
|
378
|
+
flowchart LR
|
|
379
|
+
signal[A signal fires] --> match{"kind and key<br/>match an entry?"}
|
|
380
|
+
match -- no --> shown[In the report]
|
|
381
|
+
match -- yes --> date{"past 'until'?"}
|
|
382
|
+
date -- yes --> back[Back in the report,<br/>with a line saying so]
|
|
383
|
+
date -- no --> size{"grown past 'bytes'?"}
|
|
384
|
+
size -- yes --> back
|
|
385
|
+
size -- no --> aside[Set aside,<br/>listed under 'Accepted']
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
| Field | Required | What it is |
|
|
389
|
+
| ------- | :------: | ------------------------------------------------------------------------------- |
|
|
390
|
+
| `kind` | yes | Which signal. The report prints it in grey after each one: `[dupes · date-fns]` |
|
|
391
|
+
| `key` | | Which instance. Leave it out to accept every instance — a bigger decision |
|
|
392
|
+
| `why` | yes | The reason. An acceptance without one is ignored, and said so |
|
|
393
|
+
| `who` | | Somebody a reader can ask in a year |
|
|
394
|
+
| `until` | | `YYYY-MM-DD`. After it the signal comes back |
|
|
395
|
+
| `bytes` | | The size that was agreed. If the signal grows past it, it comes back |
|
|
396
|
+
|
|
397
|
+
The `kind` and `key` of every signal are in the text report (in grey after the signal's name) and in
|
|
398
|
+
`--format json` (`findings[].kind`, `findings[].key`). All the kinds are in the
|
|
399
|
+
[reference](CONFIG-REFERENCE.md#signals-kind-can-name).
|
|
400
|
+
|
|
401
|
+
## Answer the five questions
|
|
402
|
+
|
|
403
|
+
Some signals depend on things no build can tell — how often you release, whether people come back.
|
|
404
|
+
Answer them in the **Situation** tab of the page and export the block, or write it by hand:
|
|
405
|
+
|
|
406
|
+
```json
|
|
407
|
+
"situation": {
|
|
408
|
+
"navigation": "allDay",
|
|
409
|
+
"deploys": "weekly",
|
|
410
|
+
"returning": "most",
|
|
411
|
+
"connection": "office",
|
|
412
|
+
"priority": "firstScreen",
|
|
413
|
+
"answeredBy": "@maks",
|
|
414
|
+
"answeredAt": "2026-10-01"
|
|
415
|
+
}
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
Every answer can also be `"unknown"`. The allowed values and what each one means are in the
|
|
419
|
+
[reference](CONFIG-REFERENCE.md#situation), and your editor lists them as you type.
|
|
420
|
+
|
|
421
|
+
## When it reads your build wrong
|
|
422
|
+
|
|
423
|
+
Loadline reads the build folder with rules about how tools write one: Vite, Rollup, esbuild,
|
|
424
|
+
SvelteKit, Nuxt, Stencil, Sapper, Polymer, Ember, RequireJS. A tool that writes something no rule
|
|
425
|
+
expects gets past them, and `build` is the way through without waiting for a release. Find the
|
|
426
|
+
symptom, add the line:
|
|
427
|
+
|
|
428
|
+
| What you see | Add |
|
|
429
|
+
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
430
|
+
| "No index.html … names a script", or the bootstrap is the wrong file | `"entries": ["main.*.js"]` — where the application starts |
|
|
431
|
+
| A polyfill or a copy for old browsers counted as a screen | `"ignore": ["polyfills-*.js"]` — no screen downloads it |
|
|
432
|
+
| A tab, a modal or a widget listed as a screen | `"screens": { "*.widget.ts": "piece" }` |
|
|
433
|
+
| A screen missing from the table, under "not counted as screens" | `"screens": { "src/app/admin/*": "screen" }` |
|
|
434
|
+
| The folder holds several pages and the wrong one was read | `"page": "app.html"` |
|
|
435
|
+
| Code of yours under `node_modules/` listed as a package | `"own": ["src/node_modules/**"]` |
|
|
436
|
+
| A workspace package or a vendored library counted as your code | `"dependencies": ["packages/*"]` |
|
|
437
|
+
| Every lazy chunk is a screen, and "No route table was found" although there is one | `"routeKeys": ["page"]` — the key your router imports a route's chunk under |
|
|
438
|
+
|
|
439
|
+
```json
|
|
440
|
+
"build": {
|
|
441
|
+
"entries": ["client.*.js"],
|
|
442
|
+
"ignore": ["polyfills-legacy-*.js"],
|
|
443
|
+
"screens": { "*.widget.ts": "piece", "src/app/admin/*": "screen" },
|
|
444
|
+
"page": "index.html",
|
|
445
|
+
"own": ["src/node_modules/**"],
|
|
446
|
+
"dependencies": ["packages/*", "vendor/*"],
|
|
447
|
+
"routeKeys": ["page"]
|
|
448
|
+
}
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
Names are file names or paths inside the build folder (for `screens`, the source file, or the chunk
|
|
452
|
+
when the folder has no source maps), and `*` stands for any text — the hash, a folder. What the
|
|
453
|
+
page's **not a screen** / **count as a screen** buttons say for one session, `screens` says for
|
|
454
|
+
everybody, and a click still wins over the file. What `ignore` leaves out is counted in the header
|
|
455
|
+
of the report, never dropped in silence.
|
|
456
|
+
|
|
457
|
+
For one run, `--entry <script>` on the command line says what `entries` says, and the page asks for
|
|
458
|
+
the script itself when the folder's page names none it reads; what it is given there goes into an
|
|
459
|
+
exported `loadline.json` like anything else.
|
|
460
|
+
|
|
461
|
+
`own` and `dependencies` are source paths, with `*` for a segment and `**` for any number of them,
|
|
462
|
+
matched from the start of the path. A file is yours unless it sits under `node_modules/`, and
|
|
463
|
+
Sapper's `src/node_modules/` — where an app keeps its own modules to import them by name — is read
|
|
464
|
+
as yours already. `dependencies` names the package after the folder its pattern matched:
|
|
465
|
+
`packages/*` makes `packages/ui/src/button.ts` part of a package called `ui`, which then shows in the
|
|
466
|
+
bootstrap by package, the duplicate check and every "imported by" like any other. When both match a
|
|
467
|
+
file, `own` wins. The two change what is counted as yours, so they move figures: the share of the
|
|
468
|
+
first load that is your code, the files a source map exposes, the signals about your own files.
|
|
469
|
+
|
|
470
|
+
`routeKeys` is for a router that hands a route its chunk under a key Loadline does not know. The
|
|
471
|
+
route table is found by its shape — an object with a `path` and a `component`, `loadComponent`,
|
|
472
|
+
`loadChildren`, `lazy`, `getComponent` or `asyncComponent` that imports the chunk — and a router
|
|
473
|
+
writing `{ path: "/orders", page: () => import("./orders.js") }` needs `"page"` here. Without the
|
|
474
|
+
table, every chunk loaded lazily counts as a screen. Only property names are taken.
|
|
475
|
+
|
|
476
|
+
## A complete file
|
|
477
|
+
|
|
478
|
+
```json
|
|
479
|
+
{
|
|
480
|
+
"$schema": "https://unpkg.com/@bymaksym/loadline/loadline.schema.json",
|
|
481
|
+
"tool": "loadline",
|
|
482
|
+
"version": 1,
|
|
483
|
+
"mode": "gzip",
|
|
484
|
+
"criteria": { "bootOk": "150kB", "bootBad": "300kB" },
|
|
485
|
+
"gates": {
|
|
486
|
+
"maxBoot": "350kB",
|
|
487
|
+
"maxScreen": "500kB",
|
|
488
|
+
"screens": { "map": "900kB" },
|
|
489
|
+
"maxGrowth": "20kB",
|
|
490
|
+
"failOn": "high",
|
|
491
|
+
"failOnNewPackage": true
|
|
492
|
+
},
|
|
493
|
+
"packages": ["@angular/core", "@angular/common", "@angular/router", "rxjs"],
|
|
494
|
+
"forbidden": [{ "package": "moment", "why": "We use date-fns" }],
|
|
495
|
+
"accepted": [
|
|
496
|
+
{
|
|
497
|
+
"kind": "dupes",
|
|
498
|
+
"key": "date-fns",
|
|
499
|
+
"why": "Two versions until the calendar library releases 4.x",
|
|
500
|
+
"who": "@maks",
|
|
501
|
+
"until": "2026-12-01",
|
|
502
|
+
"bytes": "14kB"
|
|
503
|
+
}
|
|
504
|
+
]
|
|
505
|
+
}
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
Read top to bottom: thresholds in gzip, the first load good up to 150 kB; the build fails over
|
|
509
|
+
350 kB of bootstrap, over 500 kB on any screen except the map, on 20 kB of growth against the
|
|
510
|
+
baseline, on any high signal — `moment` anywhere in the build is one — and on any package not on the
|
|
511
|
+
list; and one duplicated package is accepted until December, at up to 14 kB.
|