Thomas Camlong
09df2910c5
Sourced with the skills CLI - npx skills find "react performance", then
npx skills use affaan-m/ecc@react-performance, an adaptation of vercel-labs
react-best-practices: 70+ rules across 8 categories. Every mechanically
checkable rule was run against the widgets.
Seven already hold, and that is worth recording as much as a finding: no widget
registers a scroll listener, no numeric && can render a literal 0, the nested
array scans that exist are over single-digit collections, React.cache() is
applied, TanStack Query does the deduplication, content-visibility is on the six
lists that need it, and the two components-declared-in-render were already found
and fixed.
One rule this codebase deliberately contradicts: the skill prefers React 19
<Activity> over unmounting for tabs, and this pass did the opposite with
keepMounted={false}. The rule optimises for switching; a dashboard optimises for
mounting. Every board load mounts every widget while a user switches a widget's
inner tabs rarely, so building a hidden monitoring view on every page load buys
a faster switch nobody performs. Where state loss would show - custom-api's user
JSX, the edit modal's forms - the panels stay mounted.
Two candidates declined rather than guessed at, both recorded with reasoning:
the 20+ `data = []` defaults only destabilise while data is undefined, since
react-query returns a stable reference once loaded; and the 7 unlisted Mantine
entry points need two production builds and a first-load-JS diff before anyone
claims they help. @homarr/ui is not eligible at all despite 111 importers,
because Next's barrel optimiser only rewrites pure re-export files.
Also records the process error behind the earlier "no skills CLI" claim: the
entries in ~/.claude/skills are symlinks, which find -type f skips, so the
directory looked empty right after cat had succeeded on a file inside it.
127 lines
7.4 KiB
Markdown
127 lines
7.4 KiB
Markdown
# Where this left off, and what to do next
|
||
|
||
Written as a handoff. The branch is green and everything below is measured except where explicitly
|
||
marked.
|
||
|
||
## 1. Verify the unmeasured changes
|
||
|
||
Four commits apply the off-screen-row treatment beyond the one widget where it was measured. All are
|
||
typechecked and lint-clean, none are A/B'd — they are the only performance claims on this branch not
|
||
verified before commit.
|
||
|
||
| commit | widget | measured on this board? |
|
||
| --- | --- | --- |
|
||
| `7550766f6` | mediaReleases | **yes** — 135 → 55 image requests, 8346 → 5117 layout objects |
|
||
| `c526dd2b7` | mediaRequests-requestList | no — but overdraw confirmed: 1,512 px of cards in a 405 px tile, 60 images |
|
||
| `040f10594` | rssFeed, notifications, calendar event list | no — these do **not** overdraw on this board |
|
||
|
||
The last row needs care when reading a result. On the test backup rssFeed renders 7 nodes and the
|
||
calendar's 7 rows fit their tile, so a measurement will correctly show **no change**. That is not a
|
||
failure of the change — the benefit only exists for a user whose integrations return more rows than
|
||
the tile can show. To observe it, use a backup with a busier feed, or shrink the tile.
|
||
|
||
For `c526dd2b7`, which does overdraw here, a real effect is expected:
|
||
|
||
```bash
|
||
# restore two containers on identical data, one per image, then:
|
||
STRESS_BASE_URL=http://127.0.0.1:PORT STRESS_BOARD=default \
|
||
node --experimental-strip-types scripts/benchmarks/measure-board-paint.mts
|
||
```
|
||
|
||
Expect **image requests to fall**. Do **not** expect JS heap to move: decoded bitmaps live outside
|
||
`JSHeapUsedSize`. Three repeats per side — a single run wrongly suggested a −16% heap win on the first
|
||
widget. If image requests do not fall, revert it.
|
||
|
||
## 1b. What was deliberately not changed
|
||
|
||
26 widgets use `ScrollArea`; the treatment was applied to five. `content-visibility` is not free — it
|
||
costs containment work, and on content that measures itself (charts, editors, the notebook) skipping
|
||
layout can be actively wrong. The rule used: apply it where list length is decided by remote data,
|
||
leave fixed-size and chart widgets alone.
|
||
|
||
`beszelSystemStats`, `beszelSystemTable` and `beszelSystemGrid` report large row counts in the
|
||
overdraw tool, but that is the tool misreading SVG groups as rows — their content fits their tiles.
|
||
|
||
## React `cache()` and memoisation — already in place
|
||
|
||
Recorded because it looks like a gap and is not.
|
||
|
||
React `cache()` is **server-only**: it dedupes within a single RSC render and does nothing for client
|
||
widget rendering. It is already applied where it belongs — `getBoardByNameAsync`, `getHomeBoardAsync`,
|
||
`getRscServerSettingsAsync` and `getQueryClient` are all wrapped, the last with a comment explaining
|
||
the dedup.
|
||
|
||
Client-side data is cached by tRPC/react-query, whose `gcTime` was already checked and found to be
|
||
5 minutes, not the 24 hours the original fix catalogue assumed. `React.memo` is already used in the
|
||
clock, calendar and releases widgets.
|
||
|
||
## 2. The one lever with real headroom left
|
||
|
||
**The tRPC router imports every integration eagerly.** A single **16.10 MiB subtree of 460 files** is
|
||
reached by every API route, and because Next preloads route bundles it is resident before the first
|
||
request. This pays twice:
|
||
|
||
- ~41 MiB of retained bundle source (28% of the live server heap) — V8 keeps a script's source alive
|
||
while any function in it may still be lazily compiled
|
||
- ~38 MiB of V8 compiler zone memory, which is **proportional to how much JavaScript V8 compiles** and
|
||
is not reachable by any V8 flag (`--max-opt` is a null result; only `--jitless` removes it, and that
|
||
breaks rendering)
|
||
|
||
Nothing else has this profile. Every allocator and V8-level avenue is closed — see
|
||
[REJECTED.md](./REJECTED.md).
|
||
|
||
Start from `analyze-require-graph.mjs`, which found the shared subtree, and
|
||
`[root-of-the-server]__0g06wx7._.js` as the chunk reaching 460 files.
|
||
|
||
## 3. Known-good but deliberately deferred
|
||
|
||
| item | prize | why it was not done |
|
||
| --- | --- | --- |
|
||
| ASCII-escape server bundles | **9.45 MiB** | Proven mechanism — 2.00 vs 1.00 bytes/char; one char above U+00FF doubles a whole source string. Needs a build-time rewrite of minified **vendor** output, so it deserves its own PR and safety argument |
|
||
| Lazy `mysql2` / `pg` | 21.4 MiB | Three implementations, all broken; see REJECTED.md. Structurally blocked because `createDb` must stay synchronous |
|
||
| `beszelSystemStats` at 1,156 nodes | unknown | Second-heaviest widget, but its cost is chart SVG (`<g>×317`), so reducing it changes what is drawn |
|
||
| `documents` reads 18–32 | unknown | Never investigated; each document carries overhead |
|
||
| Add 7 Mantine entry points to `optimizePackageImports` | unknown | One line: `dates`, `dropzone`, `charts`, `spotlight`, `form`, `notifications`, `tiptap` are not listed, while `core`/`hooks`/`icons-react` are. Needs two production builds and a first-load-JS diff to know whether it does anything. `@homarr/ui` is **not** eligible despite 111 importers — Next's barrel optimiser only rewrites pure re-export files, and `packages/ui/src/index.ts` also defines a runtime value |
|
||
|
||
## 4. For the clean PR
|
||
|
||
The instruction was to close this experimental PR and open one with only the verified fixes, judged on
|
||
lines-of-code to performance ratio. On the evidence, that set is:
|
||
|
||
| change | size | measured effect |
|
||
| --- | --- | --- |
|
||
| `--max-semi-space-size=4` | **1 line** | −19% idle, −21% peak |
|
||
| `preloadEntriesOnStart: false` | **1 line** | −52% anon at idle; 310 fewer files even at full load |
|
||
| Umami: stop fetching 100k raw events per refresh | 1 file | −26% peak, −93% transient buffers, largest allocation 46.4 → 2.4 MiB |
|
||
| `serverExternalPackages` (mysql2/pg + 8 more) | 1 block | −21 MiB idle |
|
||
| `content-visibility` on media-release cards | 4 lines | −59% image requests, −41% layout objects |
|
||
| ssh2 WASM heap (docker-modem patch) | 1 patch | −15 to −18 MiB external at every stage |
|
||
|
||
Together these produce the headline: **−26% peak anon, −52% at idle**, no overlapping ranges at any
|
||
stage, for **+18% CPU**.
|
||
|
||
Two things to leave out or flag:
|
||
|
||
- **The gRPC patch** removes 112 files and 6 MiB from an isolated `require`, but is **not separately
|
||
visible in a full run**. Bundle hygiene, not a measured memory win.
|
||
- **Median board load reads +30%** but is **not established** — individual loads were
|
||
[506, 383, 1233] and [848, 431, 574] before against [780, 808, 515] and [621, 579, 1004] after,
|
||
heavily overlapping with no cold-then-warm pattern. If the latency trade matters, measure it properly
|
||
with many more samples; the suspicion is that it is real and concentrated in
|
||
`preloadEntriesOnStart`.
|
||
|
||
## 5. Read this before measuring anything
|
||
|
||
[METHODOLOGY.md](./METHODOLOGY.md). Every wrong number in this investigation came from an instrument,
|
||
not the application, and several were published before being caught. The short version:
|
||
|
||
- a heap snapshot **cannot** explain a peak — V8 GCs first and reports survivors only
|
||
- V8 truncates snapshot string contents to ~1 KiB
|
||
- snapshot objects are **not** live native handles
|
||
- measuring without a forced GC measures V8's growth, not a module's cost
|
||
- taking a CDP heap snapshot added **134 MiB to the process being measured**
|
||
- React per-component attribution silently returns **nothing** on a production build
|
||
- a fixed port can measure a **leftover container**
|
||
- **when a server-side change moves a client-side metric, the workload changed** — this is how
|
||
`--jitless` was caught faking a 24% win by under-rendering the page
|