homarr/docs/perf/REJECTED.md

Ideas measured and abandoned

Each of these was implemented or configured, built, and measured. They are recorded with their numbers so nobody repeats them, and because several looked like wins until the measurement came in.

Cache Components — the app cannot prerender, and the prize is ~20 ms

Tried properly: cacheComponents: true at top level on Next.js 16.3.0-preview.9. The flag is recognised (- Cache Components enabled) and the usual migration friction is absent — zero files export dynamic, revalidate or fetchCache, and experimental.dynamicIO was never set.

First blocker, and it is cheap. Everything is routed through a [locale] dynamic root segment, so the build stops before prerendering: A required root parameter (locale) was not provided in generateStaticParams. That looks like 53 routes × 38 locales = 2,014 shells, but it is not: the guide is explicit that generateStaticParams need only return one value, because with Cache Components dynamicParams: true serves the App Shell for unlisted params and upgrades it in the background. One entry for en clears it.

Second blocker, and it is structural. Past that, 111 routes fail with the same error:

Error occurred prerendering page "/en/manage/settings"
SqliteError: no such table: serverSetting

Prerendering runs at build time, and the root layout unconditionally awaits real data:

const [session, user, serverSettings, colorScheme] = await Promise.all([
  sessionPromise, userPromise, getRscServerSettingsAsync(), getCurrentColorSchemeAsync(),
]);

The immediate cause is mundane: no migration had been run, so the build had no tables. That is fixable — run the migration first and the build gets a database.

But making the error go away that way would be the wrong fix, and the error is the useful signal. If a build needs the database in order to prerender a route, the route's content is being decided at build time rather than per request. For Homarr that is actively wrong: serverSetting is per-installation data on the user's own volume, so a shell prerendered against the build machine's database would bake one install's settings into every other install's first paint. The error is Next.js correctly reporting that a request-time read sits in the shell path.

The honest fix is therefore to defer those reads into <Suspense>, not to feed the build a database. And that is where it stops being worth it: all four values feed providers that wrap children (AuthProvider session=, SettingsProvider user=), so deferring them puts essentially the whole app inside the boundary and leaves a static shell of little more than <html><body>. The build would report ◐ while shipping an empty shell — precisely the failure the migration guide warns about.

And the prize is small. Measured against a running container, warm, five repeats:

request	TTFB
/api/health/live (skips the root layout)	~3 ms
/auth/login (through the root layout)	~19–24 ms

So the layout's blocking work — auth, two DB reads, a cookie read — is worth ~16–21 ms. Not perceptible, against a root-layout restructure affecting all 53 routes plus a standing constraint on every route added afterwards.

The main screen cannot benefit at all. DynamicClientBoard is already dynamic(..., { ssr: false }) with a skeleton loading shell, so the board already paints an instant shell and renders on the client. Cache Components has no server render to unblock there; the board's real cost is client JS and tRPC round-trips, which is what the rest of this work addresses.

Two honest caveats. The ~20 ms is a warm local SQLite install; on a network database (MySQL, Postgres) or slow storage those four awaits could cost far more, and the win would scale with them. And the useful idea inside this — do not block the first byte on auth plus two DB queries — can be had without the migration, by streaming those reads in the existing layout. That is a much smaller, independently testable change and is the shape worth trying if first paint ever needs attention.

optimizePackageImports — inert, because this app builds with Turbopack

Seven Mantine entry points were absent from experimental.optimizePackageImports while @mantine/core, @mantine/hooks and @tabler/icons-react were listed: charts, dates, dropzone, form, notifications, spotlight, tiptap. Adding all seven and rebuilding:

	baseline	all seven added
client chunk files	482	482
client chunk bytes	18050.7 KiB	18050.7 KiB
largest chunk	2341.5 KiB	2341.5 KiB

Byte-for-byte identical, down to the chunk hashes. That pattern normally means a cached build — and turbopackFileSystemCacheForBuild is enabled here — so it was checked rather than written up as a null result. The Next.js documentation is explicit: "This is not needed when using Turbopack. Turbopack automatically analyzes and optimizes imports without requiring this configuration." The build banner reads Next.js 16.3.0-preview.9 (Turbopack).

So the existing three-entry list is also dead config. It is left in place as a fallback should the app ever build with webpack again, with a comment saying not to expect anything from it.

This retires the entire "barrel imports / bundle optimization" line of enquiry for this repo, including the sub-question of whether @homarr/ui — the biggest barrel at 111 importers — could be optimised. It cannot be by that mechanism, and does not need to be.

Two measurement notes for anyone revisiting this: Next 16 with Turbopack prints no size columns in its route table and emits no app-build-manifest.json, so per-route first-load JS is not available from the build output. Total bytes under .next/static/chunks is what these numbers are.

--jitless — looked like the biggest win of the entire investigation, and was fake

V8's --jitless removes the optimising compiler and all generated machine code. Its effect on code memory is real and unambiguous: code space 11.6 → 0.0 MiB. The stress figures looked spectacular: peak node RSS −24%, peak container −36%, CPU −14%, median board load 30% faster.

Three of those are impossible. The flag was applied to the server, so it cannot make the browser lighter, and removing an optimising compiler does not make code faster.

	normal	jitless
DOM nodes	8,256 / 8,280	5,442 / 5,442
JS event listeners	7,781 / 7,784	1,570 / 1,570
browser JS heap	50.0 / 49.5 MiB	28.1 / 28.2 MiB

Boards still reported 28/28 widgets ready, so the coarse check passed — but the page carries 80% fewer event listeners. Much of the UI never mounted. The memory "win" is an application doing less work, and the CPU and latency "improvements" are the same artefact.

--max-opt=2 (cap V8 at Maglev) — null result, and it closes the door

Since full jitless is unusable, capping the tier while still generating code was the obvious next try. --max-opt is rejected by NODE_OPTIONS and accepted on the command line.

stage	full	Maglev-capped
peak anon	276.0 MiB	282.8 MiB (+2%)
boot idle	64.0 MiB	72.3 MiB (+13%)
dashboard loaded	186.1 MiB	179.2 MiB (−4%)
4 tabs	270.8 MiB	238.5 MiB (−12%)
after soak	199.0 MiB	214.3 MiB (+8%)
CPU	28.1 s	27.8 s

Render integrity was verified explicitly this time: listeners 7,784 in all four runs, DOM nodes within 40. So unlike jitless the page rendered fully and the comparison is valid — there is simply no consistent win.

The mechanism closes it permanently. Measured under --max-opt=2, peak_malloced_memory at board load is 42.1 MiB, identical to Turbofan. Maglev's zones are just as large. Capping the tier does not reduce zone memory; only not compiling does, and that breaks the page.

jemalloc — the hypothesis was backwards

~38 MiB of V8 compiler zone memory is freed back to malloc and never returned to the kernel by musl, so an allocator that decays unused spans back to the OS looked like the answer. Tested on the byte-identical image with only HOMARR_MALLOC differing, asserting the "Using jemalloc" log line.

stage	musl	jemalloc
boot idle	62.4 MiB	80.3 MiB (+29%)
after sign-in	144.9 MiB	170.6 MiB (+18%)
dashboard loaded	214.8 MiB	184.4 MiB (−14%)
4 tabs	259.9 MiB	319.6 MiB (+23%)
after soak	215.5 MiB	279.6 MiB (+30%)
CPU	28.0 s	24.5 s (−13%)

jemalloc does not release freed spans sooner; it deliberately retains more of them (thread-local caches, time-based dirty-page decay) and spends that memory on speed. musl is already the frugal choice, so "swap the allocator" is not a RAM direction. If CPU ever becomes the binding constraint, this is a measured 13% for two lines.

Lazy-loading mysql2 and pg — 21.4 MiB, three broken attempts

Both load on every SQLite install, because db/drivers/index.ts imports all three driver wrappers statically and picks one at call time. The prize is 21.4 MiB. Three attempts, each caught only by booting the real image:

1. createRequire(import.meta.url) is undefined in the CommonJS migrate.cjs bundle. It threw at load and broke startup for every dialect, including SQLite.
2. With that fixed, MySQL failed with MODULE_NOT_FOUND on drizzle-orm/mysql2/index.cjs — a dynamic require resolves through the package's require condition to a .cjs build that Next's tracing never copies into the standalone output.
3. Leaving drizzle's dialect static defeats the purpose: drizzle-orm/mysql2 imports mysql2 itself, so the client loads anyway. Verified — the built image still loaded all 77 mysql2 files.

The remaining routes are worse than the problem: forcing drizzle's .cjs into the image loads a second copy of drizzle's core beside the ESM one (straddled class identities), and the require(esm) route works only via a hardcoded absolute path, so a drizzle upgrade would break startup on two dialects. Structural blocker: createDb must stay synchronous because packages/db/index.ts does export const db = createDb(schema) at module scope and migrate.cjs is CommonJS.

Coalescing Beszel subscription updates — measured exactly zero

Three Beszel widgets account for 82% of idle DOM churn, so batching their per-record setState calls looked like an easy win. Implemented, built, measured:

	before	after
DOM mutations / 45 s	733	748
React commits / 45 s	55	55

Identical. Beszel emits roughly one record per second and the flush interval was also one second, so each flush batched exactly one record — arithmetic that should have come before the implementation.

It also exposed a unit error: DOM mutations are not re-renders. The real rates are 1.22 React commits per second for the whole board and 13.3 DOM mutations per commit. So the stats widget's "10.4 mutations/second" is about 0.8 renders per second: three live-monitoring widgets each refreshing about once a second, which is what they exist to do. 73 commits/min is the feature working, not a defect.

Next's image optimiser — 18.5 MiB shipped, 0 MiB of RAM

sharp plus @img is 18.5 MiB in the image and costs +9.1 MiB RSS once /_next/image is hit. But shouldUseNextImage={true} appears nowhere, so the logo always renders a plain <img>, and across three full 4-tab stress runs sharp never loads. images: { unoptimized: true } would save no RAM at all. The 9.1 MiB is conditional on visiting the About or Kubernetes pages; the 18.5 MiB is an image-size observation, not a memory one.

Smaller null results

idea	measured	verdict
base64 images in cache / TanStack Query / Redis	0.01 MiB (2 data-URLs), Redis totals 2.17 MB, image-proxy stores URL + headers only	the theory that started this — not a factor
orphaned zlib streams	Zlib=0 handles before and after 300 aborted gzip requests	Next's leak class does not occur here; nginx buffers the response so Next never sees the disconnect
V8 native contexts (2 → 10 under load)	0.25 MiB each, ~2.0 MiB total	too small to chase; sized before investigating
Redis 6 → 2 client consolidation	139.3 vs 139.2 MiB idle	inside noise, reverted. The pubSub:last:* TTL was kept as a real unbounded-growth fix
V8 old-space cap	removing it entirely matched the capped build at every stage	a drift ceiling, not a reduction. Kept as one line
--max-semi-space-size=2 (vs 4)	no improvement	4 is the sweet spot
--optimize-for-size, --no-opt, --lite-mode	rejected by Node in NODE_OPTIONS	not available as a runtime knob
in-image Redis / nginx removal	8.1 / 9.2 MiB RSS (3.1 PSS for nginx)	real but small, and both are load-bearing
ASCII-escaping server bundles	9.45 MiB — one char above U+00FF forces a whole source string to 2 bytes/char, proven at 2.00 vs 1.00 bytes/char	genuine, but it means rewriting minified vendor output at build time; deserves its own PR