Bundle size audit: pay-for-use tree-shaking for @solidjs/signals subsystems

[ryansolid]

Background

Solid 2.0's library size has grown substantially over 1.x, driven almost entirely by @solidjs/signals absorbing the async model (transitions, optimistic lanes, pending sources/status rails, boundaries, projections, stores). Current measurements (all uniform: esbuild bundle + minify + gzip, production defines, Jul 2026):

Full runtime (whole packages):

	Minified	Gzip
Solid 1.9.14 (core + store + web)	47.4 KB	~18.1 KB
Solid 2.0 beta (signals + solid + web)	89.5 KB	~33.5 KB
Svelte 5.56 (full client runtime)	102.6 KB	36.8 KB
React 19.2 + ReactDOM client	193.4 KB	60.3 KB

Tree-shaken minimal app (render + one signal):

	Minified	Gzip
Solid 1.x	10.6 KB	4.2 KB
Solid 2.0	31.6 KB	12.6 KB
Svelte 5 (mount)	39.7 KB	14.9 KB
React (no shaking)	193.4 KB	60.3 KB

Excluding the web runtime, the library proper is ~2.2–2.5x its 1.x size. We compare favorably against Svelte 5 and React today, but the minimal-app floor (12.6 KB gzip) means a hello-world app loads most of the async machinery whether it uses it or not.

Root cause of the high floor

1. dist/prod.js is one flat rollup bundle. Once an app imports anything, all top-level side effects in the file are retained — including the GlobalQueue._* hook installs that wire subsystems together. Module-level tree-shaking can't separate subsystems that live in the same output chunk.
2. Direct cross-subsystem calls. Some feature machinery is invoked directly from hot core paths (e.g. store proxy traps), making it reachable from createStore even when the feature is unused.

Proposed direction

• Split the published dist into chunks (rollup code splitting; index re-exports from feature chunks). All packages already declare sideEffects: false, so bundlers will drop unused chunks. Needs care around the dev/prod/node output triplet and __DEV__ replacement.
• Convert remaining direct couplings to the existing nullable-hook pattern (GlobalQueue._propagateAffects, _settleAffects, _clearOptimisticStore already demonstrate it), installed by the feature module on import.
• Add a bundle-fixture test asserting the minimal entry's size/import graph, so shaking doesn't regress silently.

Candidates (rough order of value)

• affects() — seams already in place (GlobalQueue._propagateAffects/_settleAffects); remaining work is hook-converting witnessAffectsMark (get/has traps, snapshotImpl) and inheritAffectsMarks (getNode), plus the chunk split. ~1.1–1.2 KB gzip recoverable of its ~1.3 KB cost.
• Optimistic stores / projections — same shape of problem, likely larger recovery.
• Transitions — biggest subsystem; feasibility unclear (deeply entangled with the scheduler), needs the audit to size it.
• Subsystem byte-attribution pass on the signals bundle to find anything else worth detaching.

Non-goals

Returning to the 1.x floor (4.2 KB) — the async model is load-bearing. A realistic target is a ~7–8 KB gzip minimal floor while full-featured apps pay today's price.

[ryansolid]

Ran the full audit: byte attribution, stub-and-measure experiments per subsystem, and independent re-measurement of every claim (all numbers below reproduced to the byte from a clean checkout). Method matches the issue: esbuild from src, prod defines, --mangle-props='^_', minify + gzip -9.

Bottom line: the 7–8 KB target is conservative. Rollup users are already at ~7.5 KB gzip today, and the verified upper bounds put a hooked sync-core floor at ~3.9–4.2 KB gzip for signals — essentially the 1.x floor.

Three corrections to this issue's framing

1. The flat bundle is not the villain — chunk-splitting the dist recovers almost nothing. Against the published flat prod.js, the minimal-core fixture measures 18.8 KB min / 7.5 KB gz under Rollup+terser vs 20.4 / 8.4 under esbuild (both better than from-src esbuild, 21.8 / 8.9). Rollup's multi-pass literal tracking dead-branches the latest/pending/refresh rails inside read() once their writers shake off. A dist chunk split recovers ~1.1 KB min for Rollup users, ~1.7 KB for esbuild users. The recoverable mass is reachable via direct calls from read/write/flush in every build — only the nullable-hook conversion gets it back.
2. The retention has three specific structural shapes: (a) direct imports from hot functions — recompute calls handleAsync/clearStatus (core.ts:281/284), so all of async.ts is retained by any primitive; (b) unshakeable class members — globalQueue = new GlobalQueue() (scheduler.ts:852) pins the entire transition orchestration living inside flush(); (c) hook installers in the wrong module — GlobalQueue._propagateAffects/_settleAffects are installed as top-level side effects of async.ts (async.ts:591), which core hard-imports, defeating the seam. (The working seams — _clearOptimisticStore, _releaseAffectsScope — work precisely because their installers live in store/*.) Also: heap.ts is not async bloat; it's the plain dirty queue and stays.
3. affects() costs ~0.9 KB gz, not ~1.3 (2,477 min / 897 gz full-bundle, verified). The bigger problem is next door: affects.ts:4 hard-imports getStoreAffectsNodes from store/store.ts, so using affects in a store-less app drags in 8.3 KB min of store machinery.

What each feature costs today (cumulative, from src)

Step	Min	Gzip
Core floor (signal/memo/effect/root/flush)	21.8 KB	8.9 KB
+ owner/context utilities	22.5	9.1
+ async surface (isPending, latest, action…)	24.4	9.9
+ createStore	37.9	14.6
+ reconcile, projections, optimistic	38.1	14.7
+ mapArray/repeat	41.2	15.7
+ boundaries/flatten	45.8	17.4
+ affects	46.9	17.8
Full package	53.4	20.0

Async APIs cost +1.9 KB because the machinery is pre-paid in the floor — the issue's thesis confirmed. The other headline is the createStore cliff: 5.5 KB of it is reconcile.ts + projection.ts retained by one static import (store.ts:36 — the derived-form overload calls createProjectionInternal, which calls reconcile), even when neither is used.

Verified subsystem experiments (stub = upper bound; independently re-measured)

Detached	Fixture	Δ min	Δ gzip
async + transitions + lanes	core floor	−13,802	−5,334
optimistic + projections	store subset	−7,158	−2,509
optimistic + projections	full	−3,872	−1,390
affects (all of it)	full	−2,477	−897

A production hook conversion of the async/transition subsystem keeps ~0.7–1.2 KB min of shims + the error rail → realistic signals floor ~8.7–9.2 KB min / 3.9–4.2 KB gz (~5.5 KB gz minimal app incl. web).

Revised plan

Phase 1 — no dist restructuring, all verified (≈1.5 KB gz off the floor, ≈2.8 KB gz off store apps):

• Hook-convert createProjectionInternal in createStore's derived overload → store fixture 14.1 → 11.8 KB gz. Smoke-tested variant already validated.
• Split async.ts into status-rails vs drivers; handleAsync/applyAffectsReads behind nullable GlobalQueue statics → −2,166 min / ~900 gz on the floor. The split is a precondition: core imports clearStatus/notifyStatus, so hooks installed from today's async.ts recover zero.
• Move _propagateAffects/_settleAffects installers into affects.ts; hook affects.ts's getStoreAffectsNodes import.
• Companion (isPending/latest) machinery behind hooks → −1,245 min / −541 gz.
• /* @__PURE__ */ on three top-level initializers (storePath Object.assign, projection createWriteTraps(), boundaries createContext) → ~1.1 KB for dist consumers.
• Bundle-fixture test asserting the minimal entry's size + retained-module graph, so this can't regress silently.

Phase 2 — transitions/lanes/optimistic hook conversion (the 5.3 KB gz prize). 38 seams, 25 hot-path but concentrated into gate points already idiomatic in-tree (nullable GlobalQueue statics, per-node null fields, sticky counters). Two design rulings needed first: collapsing read()'s five async guards into one epoch check, and the semantic fork — two-phase write staging is documented core behavior and stays; a minimal build changes what createMemo does with a promise-returning function.

Phase 3 — web/dist: <Loading> hydration-resume behind enableHydration() (2.4 KB for CSR apps), dedupe the DOMElements set in dom-expressions (286 entries, 149 unique, ~1 KB), fix IS_DEV not const-folding across modules under esbuild, revisit dist terser config (compress:false + keep_fnames + prettier costs CDN users ~5.8 KB gz).

Two traps for the implementation

• sideEffects: false becomes a lie under chunk splitting. Bundlers legally drop unreferenced modules including their top-level hook installs (reproduced: same src without the flag measures +2 KB because the installs pin everything back). Feature entries must be structured so importing the feature's API references its installer.
• Property mangling (^_) across split chunks breaks at runtime unless mangling is a single pass or uses a shared persisted nameCache — @rollup/plugin-terser runs per-chunk in workers, so _pendingValue can mangle differently per chunk.

Constraints review (against SPEC-ASYNC-SEMANTICS / INTERNALS): the status rails are a three-tenant contract — plain-effect error routing (A1–A5) must stay in core (~300–400 bytes); A17 forbids read-path indirection over overrides; A10 probe bookkeeping stays in core read(); INV-3's sanctioned notify site transfers to the hook; Tier-A tests are spec — the fully-loaded chunked build must pass them unchanged. Also confirmed non-findings: dev diagnostics already fully shake from prod, and reconcile's twin fast/slow paths are load-bearing (merging measured net-negative on gzip).

Phase 1 PR incoming.

🤖 Audit run with Claude Code

[ryansolid]

Phase 1 is up: #2885. Two design rulings made during implementation reshape the roadmap above:

1. createStore's derived overload keeps its static coupling to projection/reconcile — the overload symmetry matters more than the ~2.3 KB gz recovery for plain-store users. The "derived-form hook" item is dropped.
2. The appearance of a promise is the only async trigger. A promise-returning createMemo must work in every build, so handleAsync and the transition machinery are core by definition — no import opts into them. This retires the _handleAsync hook item and bounds Phase 2: what remains detachable is what you explicitly import (optimistic APIs within the promise ruling, plus web-side seams), not the full 5.3 KB gz async subsystem the audit measured as the ceiling.

What landed in #2885: affects() and isPending()/latest() fully pay-for-use behind nullable hooks, per-module dist (preserveModules + single-pass shared-nameCache property mangling), PURE annotations, and a tree-shake regression test. One finding worth recording: the flat dist actively regressed (+721 min) once hooks existed — top-level hook installs are unshakeable side effects in a single file — so the chunk split moved from "nice to have" to "required to ship the wins."

Minimal app from the published dist: 12,656 → 11,366 gz (−10%); core floor from src: 8,885 → 8,154 gz.

🤖 Audit and implementation with Claude Code