Analyzing Backend Bundle

Analyzing the backend bundle

The backend bundles (apps/server/dist, apps/desktop/dist) are esbuild ESM output with code splitting: an entry plus chunks/, where a chunk loads only when a dynamic import() first needs it. Every megabyte the process loads at startup costs three ways, permanently:

• Retained source (~1 MB heap per loaded MB): V8 keeps each loaded script's source string for the life of the script. Double that for a chunk containing any character above U+00FF — esbuild escapes strings (charset: "ascii") but emits regex literals verbatim, and one raw Arabic digit stores the whole chunk two-byte.
• Parser high-water (~5 B native per loaded byte, cold start): V8's parse of the loaded code peaks in malloc'd memory that glibc keeps as dirty pages after it is freed. NODE_COMPILE_CACHE roughly halves it on warm starts.
• Bytecode and metadata in the JS heap.

Reference points (2026-08, Node 22, real 146 MB DB, same source built both ways; the full table is in PR #11111): the monolithic 14.8 MB CJS bundle cost 207 MB RSS / 64 MB heap post-GC and 1 177 ms to first HTTP response; the split ESM build loaded 7.65 MB at startup and cost 120 MB / 42 MB and 895 ms, with the V8 parser's native peak down from 78 MB to 21 MB. ESM without seams matched CJS on every metric — splitting only pays through dynamic-import boundaries. So the question that matters is never "how big is the bundle" but "how much of it loads at startup" — and the tools here answer it with runtime evidence, not static guessing.

Tools

All in this folder, zero dependencies. record and profile-bundle boot the real server, so they need the usual environment (adapt paths; use a scratch copy of a real document.db for realistic becca numbers, or an empty dir for setup-mode):

ENV="TRILIUM_ENV=production TRILIUM_DATA_DIR=<scratch>/data TRILIUM_PORT=8123 \
     TRILIUM_RESOURCE_DIR=$PWD/apps/server/dist"

# 1. Record which dist/ files the server loads at startup (ground truth):
env $ENV node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs record \
    --bundle apps/server/dist/main.mjs --out /tmp/loaded.txt --port 8123

# 2. Join with the metafile: eager vs lazy totals, per package, biggest eager chunks:
node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs startup \
    --meta <meta.json> --loaded /tmp/loaded.txt

# 3. Explain WHY a package is eager (shortest static import chain from the entry;
#    --from <input> traces from a module that is itself dynamically imported):
node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs why \
    --meta <meta.json> iconv-lite undici
node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs why \
    --meta <meta.json> --from apps/server/src/www.ts highlight.js

# 4. Whole-bundle composition, no boot needed:
node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs packages --meta <meta.json>

# 5. After adding any lazy seam — catches the CJS interop break described below:
node .claude/skills/analyzing-backend-bundle/check-dynamic-imports.mjs apps/server/dist

# Memory numbers (RSS/heap post-GC; add --snapshot for a heap snapshot):
env $ENV node --expose-gc .claude/skills/analyzing-backend-bundle/profile-bundle.cjs \
    apps/server/dist/main.mjs --port 8123 --snapshot /tmp/s.heapsnapshot

# Startup speed (spawn -> first HTTP response, median of N runs):
env $ENV node .claude/skills/analyzing-backend-bundle/bench-startup.mjs \
    apps/server/dist/main.mjs 5

# What the heap actually retains (proves which chunk sources are resident):
node --max-old-space-size=8192 .claude/skills/analyzing-backend-bundle/heap-strings.mjs \
    /tmp/s.heapsnapshot

The desktop bundle embeds the same server code, so server recordings generalize to it; record/profile-bundle cannot boot apps/desktop/dist/main.mjs under plain node (it imports electron), but packages and why work on its metafile directly.

Getting the metafile

buildBackend() writes dist/meta.json, and the last call in the app's build script wins — after pnpm server:build it describes image_worker.cjs, not main. To get the main bundle's metafile, temporarily leave only the main.ts buildBackend call in apps/server/scripts/build.ts, run the build, and save dist/meta.json elsewhere before restoring. (Making buildBackend write per-entry metafiles is the real fix if this grates.)

Interpreting the results

• Eagerness is decided only by the recording. The metafile marks every dynamic-import target chunk with entryPoint (240 of 286 outputs in the first analysis), so any static reasoning that consults entryPoint, or assumes "chunk = lazy", overcounts. Conversely the static-reachability closure undercounts: a dynamic import executed during boot loads its chunk anyway.
• "NOT statically reachable" + present in the startup set has two causes, and they call for opposite fixes. Either a dynamic import runs during startup — the seam exists and boot-time code defeats it, so defer that call (example: the /mcp route registering the MCP SDK at boot instead of on first request) — or the package is reached by an ordinary static chain from a module that is itself dynamically imported at boot, such as apps/server/src/www.ts. why --from apps/server/src/www.ts <pkg> shows the second kind; the fix there is a seam somewhere along the chain it prints.
• why takes a package name, not a substring. A bare needle matches at node_modules/<name>/ or a whole path segment, because plain substring matching silently confuses a package with any file whose name merely ends the same way — "highlight.js" also appears in postcss's terminal-highlight.js, which reads as a plausible but entirely fictitious dependency edge.
• Chunks load as units. A package can be "lazy" in source but ride in a chunk shared with eager code; startup's biggest-chunks table shows each chunk's dominant input so this is visible.
• A why chain through an absurd path is a stubbing opportunity — e.g. highlight.js reached via sanitize-html → postcss/lib/terminal-highlight (postcss's terminal error pretty-printer). An esbuild alias to a stub kills such an edge at build level.