@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.
Files changed (115) hide show
  1. package/README.md +272 -45
  2. package/dist/cli/cli/args.js +97 -116
  3. package/dist/cli/cli/gates.js +80 -14
  4. package/dist/cli/cli/main.js +275 -31
  5. package/dist/cli/cli/memory.js +114 -0
  6. package/dist/cli/cli/read/declared.js +52 -0
  7. package/dist/cli/cli/read/locate.js +214 -0
  8. package/dist/cli/cli/{read-build.js → read/read-build.js} +156 -87
  9. package/dist/cli/cli/read/read-config.js +120 -0
  10. package/dist/cli/cli/render/html-report.js +111 -0
  11. package/dist/cli/cli/render/render-agent.js +114 -0
  12. package/dist/cli/cli/render/render-asked.js +104 -0
  13. package/dist/cli/cli/render/render-badge.js +140 -0
  14. package/dist/cli/cli/{render-json.js → render/render-json.js} +26 -10
  15. package/dist/cli/cli/{render-markdown.js → render/render-markdown.js} +6 -6
  16. package/dist/cli/cli/{render-pr.js → render/render-pr.js} +37 -15
  17. package/dist/cli/cli/{render-sarif.js → render/render-sarif.js} +11 -6
  18. package/dist/cli/cli/{render-text.js → render/render-text.js} +169 -127
  19. package/dist/cli/cli/render/terminal.js +55 -0
  20. package/dist/cli/cli/report.js +76 -29
  21. package/dist/cli/cli/self-check.js +19 -23
  22. package/dist/cli/cli/since-last.js +45 -0
  23. package/dist/cli/cli/text/text-errors.js +124 -0
  24. package/dist/cli/cli/text/text.js +343 -0
  25. package/dist/cli/cli/text/usage.js +240 -0
  26. package/dist/cli/src/app/core/analysis/analysis.js +68 -24
  27. package/dist/cli/src/app/core/analysis/{barrels.js → graph/barrels.js} +10 -3
  28. package/dist/cli/src/app/core/analysis/{blast.js → graph/blast.js} +56 -17
  29. package/dist/cli/src/app/core/analysis/{cycles.js → graph/cycles.js} +1 -1
  30. package/dist/cli/src/app/core/analysis/{importers.js → graph/importers.js} +1 -1
  31. package/dist/cli/src/app/core/analysis/{insights.js → graph/insights.js} +10 -4
  32. package/dist/cli/src/app/core/analysis/invariant.js +1 -1
  33. package/dist/cli/src/app/core/analysis/metafile.types.js +21 -7
  34. package/dist/cli/src/app/core/analysis/{delivery.js → screens/delivery.js} +1 -1
  35. package/dist/cli/src/app/core/analysis/{entries.js → screens/entries.js} +87 -11
  36. package/dist/cli/src/app/core/analysis/screens/marks.js +32 -0
  37. package/dist/cli/src/app/core/analysis/screens/route-files.js +116 -0
  38. package/dist/cli/src/app/core/analysis/{sourcemap.js → sourcemap/sourcemap.js} +106 -7
  39. package/dist/cli/src/app/core/analysis/{split-drift.js → sourcemap/split-drift.js} +13 -7
  40. package/dist/cli/src/app/core/analysis/tool.js +83 -0
  41. package/dist/cli/src/app/core/assets/assets.js +137 -16
  42. package/dist/cli/src/app/core/baseline/baseline.js +0 -0
  43. package/dist/cli/src/app/core/{intake → build-text}/index-html.js +234 -29
  44. package/dist/cli/src/app/core/build-text/route-table.js +178 -0
  45. package/dist/cli/src/app/core/build-text/tool-marks.js +54 -0
  46. package/dist/cli/src/app/core/caching/caching.js +123 -45
  47. package/dist/cli/src/app/core/caching/from-analysis.js +20 -4
  48. package/dist/cli/src/app/core/config/config-text.js +90 -0
  49. package/dist/cli/src/app/core/config/config-values.js +358 -0
  50. package/dist/cli/src/app/core/config/loadline-config.js +81 -16
  51. package/dist/cli/src/app/core/config/merge-config.js +98 -0
  52. package/dist/cli/src/app/core/deps/deps.js +141 -23
  53. package/dist/cli/src/app/core/deps/pins.js +63 -0
  54. package/dist/cli/src/app/core/export/summary.js +54 -12
  55. package/dist/cli/src/app/core/findings/actions.js +65 -6
  56. package/dist/cli/src/app/core/findings/bundle/boot-single.js +76 -0
  57. package/dist/cli/src/app/core/findings/bundle/dupes.js +68 -0
  58. package/dist/cli/src/app/core/findings/{graph.js → bundle/graph.js} +32 -20
  59. package/dist/cli/src/app/core/findings/{own-in-boot.js → bundle/own-in-boot.js} +9 -5
  60. package/dist/cli/src/app/core/findings/{requests.js → bundle/requests.js} +3 -3
  61. package/dist/cli/src/app/core/findings/{shipped.js → bundle/shipped.js} +30 -18
  62. package/dist/cli/src/app/core/findings/compose.js +6 -1
  63. package/dist/cli/src/app/core/findings/effort.js +4 -0
  64. package/dist/cli/src/app/core/findings/finding.types.js +2 -0
  65. package/dist/cli/src/app/core/findings/findings.js +68 -55
  66. package/dist/cli/src/app/core/findings/{assets.js → folder/assets.js} +65 -16
  67. package/dist/cli/src/app/core/findings/{caching.js → folder/caching.js} +17 -10
  68. package/dist/cli/src/app/core/findings/{page.js → folder/page.js} +6 -2
  69. package/dist/cli/src/app/core/findings/{scan.js → folder/scan.js} +37 -13
  70. package/dist/cli/src/app/core/findings/kind-names.js +163 -0
  71. package/dist/cli/src/app/core/findings/{deps.js → supplied/deps.js} +13 -8
  72. package/dist/cli/src/app/core/findings/supplied/forbidden.js +71 -0
  73. package/dist/cli/src/app/core/findings/{situation.js → supplied/situation.js} +2 -2
  74. package/dist/cli/src/app/core/findings/text/causes.js +39 -0
  75. package/dist/cli/src/app/core/findings/text/finding-html.js +33 -0
  76. package/dist/cli/src/app/core/findings/{finding-text.js → text/finding-text.js} +307 -103
  77. package/dist/cli/src/app/core/findings/text/tool-advice.js +97 -0
  78. package/dist/cli/src/app/core/format/format.utils.js +172 -18
  79. package/dist/cli/src/app/core/format/ownership.js +93 -0
  80. package/dist/cli/src/app/core/i18n/en.js +180 -61
  81. package/dist/cli/src/app/core/i18n/es.js +192 -68
  82. package/dist/cli/src/app/core/intake/bundle-graph.js +285 -46
  83. package/dist/cli/src/app/core/intake/dist-files.js +87 -16
  84. package/dist/cli/src/app/core/intake/embedded.js +56 -0
  85. package/dist/cli/src/app/core/intake/unreached.js +139 -0
  86. package/dist/cli/src/app/core/intake/webpack-modules.js +185 -0
  87. package/dist/cli/src/app/core/intake/webpack-stats.js +298 -0
  88. package/dist/cli/src/app/core/project/budget-advice.js +14 -10
  89. package/dist/cli/src/app/core/project/project-context.js +89 -19
  90. package/dist/cli/src/app/core/project/project-name.js +36 -0
  91. package/dist/cli/src/app/core/scan/scan.js +116 -39
  92. package/dist/cli/src/app/core/scan/secrets.js +0 -0
  93. package/dist/cli/src/app/core/situation/situation-text.js +23 -0
  94. package/dist/cli/src/app/core/situation/situation.js +9 -8
  95. package/dist/cli/src/app/core/timing/timing.js +5 -2
  96. package/dist/cli/src/app/core/whatif/defer.js +29 -4
  97. package/dist/cli/src/app/core/whatif/source-importers.js +58 -0
  98. package/dist/cli/src/app/core/whatif/why.js +102 -0
  99. package/dist/cli/src/app/state/report-messages.utils.js +1 -4
  100. package/docs/CONFIG-REFERENCE.md +230 -0
  101. package/docs/CONFIG.md +511 -0
  102. package/docs/HOW-IT-WORKS.md +286 -25
  103. package/loadline.html +26 -24
  104. package/loadline.schema.json +1209 -0
  105. package/package.json +71 -35
  106. package/dist/cli/cli/text.js +0 -180
  107. package/dist/cli/src/app/core/findings/finding-html.js +0 -13
  108. /package/dist/cli/cli/{read-build.types.js → read/read-build.types.js} +0 -0
  109. /package/dist/cli/cli/{render-json.types.js → render/render-json.types.js} +0 -0
  110. /package/dist/cli/cli/{text.types.js → text/text.types.js} +0 -0
  111. /package/dist/cli/src/app/core/analysis/{exclusive.js → graph/exclusive.js} +0 -0
  112. /package/dist/cli/src/app/core/analysis/{insights.types.js → graph/insights.types.js} +0 -0
  113. /package/dist/cli/src/app/core/analysis/{module-graph.js → graph/module-graph.js} +0 -0
  114. /package/dist/cli/src/app/core/analysis/{sourcemap.types.js → sourcemap/sourcemap.types.js} +0 -0
  115. /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.