Problem
An adopter who edits a pantry/@stacksjs/stx/src/*.ts file has to manually track FIVE layers of staleness before the change reaches the browser:
- Pantry src — the file you edit
- Pantry dist — must rebuild with
bun build.tsafter src edit node_modules/@stacksjs/stx/dist/— Bun.resolveSync resolves here, NOT pantry. May or may not be symlinked.bun-plugin-stxbundled runtime — itsserve.tsbundles the runtime at boot, caches in memory_cachedSignalsRuntimemodule-level cache — insidecaching.ts, persists across requests until process restart
I personally hit each of these in the last week. The maintainer hit it too in their #1737 close comment ("the bug was a #1735 stale-bundled-runtime failure mode"). It's a real, repeated developer experience problem.
Symptoms
- Edit
pantry/@stacksjs/stx/src/signals.ts, restart dev server, change doesn't appear → forgot to rebuild dist - Rebuild dist, restart dev server, change doesn't appear →
node_modules/@stacksjs/stxisn't symlinked to pantry - Symlink + restart, change doesn't appear → bun-plugin-stx cached the runtime in memory pre-restart
- Restart bun-plugin-stx, change doesn't appear →
_cachedSignalsRuntimewas hit by a request between restart and your verify-curl - Hard-reload page, change doesn't appear → browser cached the old runtime IIFE blob
That's a 5-level fan of "did I clear all the caches?"
Proposed
A. Auto-rebuild pantry dist on src edit
Watch pantry/@stacksjs/stx/src/** in dev mode. On change:
- Run
bun build.tsautomatically - Invalidate
_cachedSignalsRuntime - Send HMR signal to all connected browsers
Same pattern as Vite's dependency pre-bundling watch.
B. Symlink node_modules/@stacksjs/stx → pantry/@stacksjs/stx by default
If pantry/@stacksjs/stx exists, bun install should symlink the corresponding node_modules/@stacksjs/stx entry to it. Adopter doesn't have to remember to do this manually.
Per project memory project_stx_pantry_override.md: "pantry is canonical for framework packages." The framework should enforce that resolution path.
C. Invalidate _cachedSignalsRuntime on every dev-mode dist change
Today's caching.ts:113:
if (debug) {
// In debug mode, always regenerate to avoid stale runtime issues
const { generateSignalsRuntimeDev } = await import('./signals')
return generateSignalsRuntimeDev()
}
if (_cachedSignalsRuntime === null) { ... }
return _cachedSignalsRuntimeIn dev mode (non-debug), the cache is held forever. Should be:
- File-mtime-based invalidation (check
dist/signals.jsmtime on each request, regenerate if changed) - OR file-watcher-driven invalidation
D. Make the resolution clear in ./buddy doctor
$ ./buddy doctor
stx runtime resolution:
✓ pantry/@stacksjs/stx/src/signals.ts (mtime: 5 min ago)
✓ pantry/@stacksjs/stx/dist/signals.js (mtime: 4 min ago, rebuilt after src ✓)
✓ node_modules/@stacksjs/stx → pantry (symlinked correctly)
✓ bun-plugin-stx loaded from: pantry/bun-plugin-stx/dist/serve.js
✓ Served runtime length: 100956 chars (matches expected)If any step is misaligned, error clearly:
$ ./buddy doctor
stx runtime resolution:
✓ pantry/@stacksjs/stx/src/signals.ts (mtime: 5 min ago)
✗ pantry/@stacksjs/stx/dist/signals.js (mtime: 2 hours ago, OLDER than src by 1h 55m)
→ Run: cd pantry/@stacksjs/stx && bun build.ts
⚠ node_modules/@stacksjs/stx is a real dir, NOT symlinked to pantry
→ Run: rm -rf node_modules/@stacksjs/stx && ln -s ../../pantry/@stacksjs/stx node_modules/@stacksjs/stxPrior art
- Vite — file watcher rebuilds dependencies + invalidates cache + HMRs the browser. Zero manual steps.
- Next.js — same model.
- Vue CLI / Vue dev server — same.
- SvelteKit — same.
The "edit source, see change in browser" loop is table stakes. Stacks today has the longest "edit-to-see" lag of any modern framework I've worked in.
Impact
- Per-edit time: cuts dev-loop iteration time from ~30 sec (manual rebuild + restart cycle) to ~3 sec (auto).
- Cognitive load: adopters stop tracking "did I clear cache N?" — there is one cache and it's managed.
- Onboarding: new adopter setup goes from "follow the symlink + rebuild checklist" to "just
bun installand run."
Phasing
- Phase 1:
./buddy doctorreports staleness clearly (Section D) - Phase 2: File-mtime invalidation of
_cachedSignalsRuntime(Section C) - Phase 3: Auto-symlink node_modules → pantry on
bun install(Section B) - Phase 4: Watch + auto-rebuild pantry dist in dev mode (Section A)
Happy to PR Phase 1.