docs(findings): the App Router churn claim was wrong; idle churn is Beszel

Corrects the largest wrong claim in this work. Earlier rounds reported that ~80% of
idle React commits entered at Next's internal HeadManagerContext and that "the App
Router root re-renders about once a second", and named it the highest-value next step.

Both are false. Measuring the same idle churn against boards of different sizes:

  board      items   idle commits/min
  hey            0                0.0
  footbol        3                0.0
  default       28               76.0

A 3-item board commits zero times per minute. If the router re-rendered on a timer,
every board would churn regardless of its contents.

The original attribution was a tooling artefact. measure-rerenders.mts decides a fiber
re-rendered from fiber.actualDuration, which only a React *profiling* build populates.
On a production build every fiber fails that test and both attribution tables come back
empty - and an empty table reads as "nothing re-rendered" rather than "this build cannot
tell you". The harness now says which case it is, and waits for the board container to be
attached rather than visible so a zero-item board can be measured at all - that control
is what disproved the claim.

Adds measure-widget-churn.mts, which attributes churn on a production build via DOM
mutations keyed to the nearest [data-type="item"] ancestor. On the 28-item board, idle
for 45s:

  470  beszelSystemStats      64%
   77  beszelSystemTable      11%
   52  beszelSystemGrid        7%
   22  dockerContainers        3%
   93  (outside any widget)   13%

Three Beszel widgets are 82% of all idle churn, one of them 64% on its own at 10.4
mutations per second.

Also logs what Next.js itself costs, since it was assumed to be the problem: its loaded
source is a flat 3.47 MiB (364 framework files + 32 vendored) and does not grow at all
between boot and a fully loaded multi-tab session, while Homarr's own chunks grow from
3.73 to 15.44 MiB. Next is 16.1 MiB on disk; the largest things it vendors are its
next-server runtime (1.60), @edge-runtime (0.85), edge-runtime (0.51) and compression
(0.30). The framework is not where this application's memory goes.
This commit is contained in:
Thomas Camlong committed 2026-08-10 17:45:12 +02:00
1 parent ab5b8dad43
commit 9f1a15b9bf
3 files changed
+180 -23

No files matched your search

+50 -13
View File
@@ -283,23 +283,60 @@ point where the update entered the tree.
re-renders over 30,000 times. That is the churn behind the 650 MB peak: it is transient
allocation, not retention.
Roughly 80% of those commits enter at the *same place*: an anonymous provider at depth 2
whose props are `[value, children]` and whose value is `{appDir}` — Next.js's internal
`HeadManagerContext`. Its value is a fresh object literal on every App Router render, so
each one re-renders the entire application below it. The remainder enter around
`__next_metadata_boundary__` / `<title>`, which points the same way.
> ### Correction: this was wrong, and it was the wrong thing to chase
>
> An earlier round of this work concluded that ~80% of commits entered at an anonymous depth-2
> provider with props `[value, children]` and value `{appDir}` — Next's internal
> `HeadManagerContext` — and therefore that "the App Router root re-renders about once a second"
> was the dominant cost and the highest-value next step.
>
> **Both claims are false.** Measuring the same idle churn against boards of different sizes:
>
> | board | items | idle commits/min |
> | --- | --- | --- |
> | `hey` | 0 | **0.0** |
> | `footbol` | 3 | **0.0** |
> | `default` | 28 | **76.0** |
>
> A 3-item board commits **zero** times per minute. If the App Router re-rendered on a timer,
> every board would churn regardless of its contents. The churn is entirely widget-driven.
>
> The original attribution was an artefact: `measure-rerenders.mts` decides a fiber re-rendered
> from `fiber.actualDuration`, which **only a React profiling build populates**. On a production
> build every fiber fails that test and both attribution tables come back empty — and an empty
> table reads as "nothing here" rather than "this build cannot tell you". The tool now says which
> case it is instead of printing nothing. The depth-2 provider was whatever survived that filter
> in a profiling build, not the cause.
So the dominant cost is the **App Router root re-rendering about once a second**, not any
individual widget. No polling `router.refresh()` exists in application code, so the
trigger is inside Next's own router/metadata handling and is not fixed by anything in
this PR. That is the next thing to chase, and it is worth more than any further
component-level tuning: everything else is downstream of it.
Attribution that works on a production build uses DOM mutations instead —
`scripts/benchmarks/measure-widget-churn.mts`. Every re-render that changes anything observable
mutates the DOM, and the mutated node's nearest `[data-type="item"]` ancestor names the widget.
On the 28-item board, idle for 45 s:
| widget | mutations | share |
| --- | --- | --- |
| **beszelSystemStats** | **470** | **64%** |
| beszelSystemTable | 77 | 11% |
| beszelSystemGrid | 52 | 7% |
| dockerContainers | 22 | 3% |
| immich-albumCarousel | 14 | 2% |
| downloads | 4 | 1% |
| (outside any widget) | 93 | 13% |
**Three Beszel widgets account for 82% of all idle churn**, one of them for 64% on its own, at
10.4 mutations per second.
The mechanism is in `packages/widgets/src/beszel/_shared/use-live-stats.ts`: the tRPC
subscription's `onData` called `setSystemStats((prev) => [...prev, record])` — one React state
update per record, each allocating a fresh 60-element array. Beszel pushes one record per second
*per system*, plus one per container, so a widget watching several systems drives a steady stream
of renders. Records are now accumulated outside React and flushed once a second, which is the
fastest a 60-second sliding-window chart can meaningfully show. Nothing is dropped.
`useTimeAgo` was calling `setState` every second even when the rendered label was
unchanged ("3 minutes ago" holds for a minute), so it now compares before setting. This
is a correctness fix — idle commits stayed within their 73–96 range afterwards, because
the app-root churn dominates and this hook is not what drives it. Recorded as *not* a
measured win.
is a correctness fix — idle commits did not move measurably, because the Beszel widgets
dominate and this hook is not what drives them. Recorded as *not* a measured win.
## What is actually hogging the memory