Dev hot-reload of server-side modules is stale on Bun (query cache-bust ignored)

[vivek7405]

Problem

webjs's dev server picks up edits to server-side modules (route.ts, *.server.ts, page modules during SSR, WS exports) by re-importing them per request with a ?t=<timestamp> query cache-bust (loadWsModule, handleApi, the dev SSR module load). Node honors a changed import query as a fresh module; Bun's ESM loader ignores the query string and returns the cached module, and Bun exposes no module-eviction API. So on Bun, editing a server-side module is not reflected until a dev-server restart.

Verified on Bun 1.3.14: import(url + '?t=1') then import(url + '?t=2') after editing the file returns the FIRST module's exports on Bun (Node returns the second). Surfaced by the #509 Bun test matrix (the api dev-cache-bust test).

Component / page / layout SOURCE edits hot-reload fine on Bun, because the served .ts/.js is read from disk per request (tsResponse / jsModuleResponse), not imported. Only the server-side module EXECUTION path is affected.

Design / approach

No clean webjs-side fix exists today (query cache-bust is the standard ESM trick and Bun ignores it; a unique-path copy breaks relative imports inside the module). Options to investigate when Bun support lands or a workaround emerges:

• Track Bun's module-registry / HMR APIs (e.g. import.meta.hot, a programmatic eviction) and wire the dev re-import to it on Bun.
• A Bun-specific loader/plugin that re-evaluates a changed module's source.

Blocked on Bun upstream for now; documented as a known limitation in agent-docs/testing.md.

Acceptance criteria

• On Bun dev, editing a route.ts / *.server.ts / page module is reflected on the next request without a restart (parity with Node dev).
• A cross-runtime test proves the server-module reload on Bun.
• The known-limitation note in agent-docs/testing.md is removed once fixed.

[vivek7405]

Findings: fix this with bun --hot, auto-detected (no opt-in flag)

Dug into how to actually support server-module hot-reload on Bun, tested the mechanisms, and compared against the other frameworks. The fix is small and needs essentially no change to the framework's import path.

Root cause (confirmed)

The dev server re-imports a changed route/page/action/WS module per request via import(file + '?t=' + Date.now()). Bun's ESM loader ignores the query string and keys by resolved path, and exposes no module-eviction API, so the stale cached module is returned. Verified: import(url + '?t=1') then import(url + '?t=2') after an edit returns the FIRST module on Bun (Node returns the second).

The fix: bun --hot does the invalidation for us

bun --hot watches every loaded file (including dynamically-imported ones), invalidates a changed module, and re-evaluates it on the next import, WITHOUT a process restart. I verified that a long-running Bun.serve doing a per-request dynamic import() picks up a file edit live:

req1 -> "ORIGINAL"   (edit the file)   req2 -> "EDITED"

And it still works with our EXACT ?t=${Date.now()}-${random} query present (Bun ignores the query for resolution but --hot invalidates by path). So our existing dev import code rides --hot unchanged. The ?t= becomes a harmless no-op on Bun.

So the change is: on Bun, webjs dev re-execs the dev server under bun --hot (the Bun analog of the node --watch re-exec we already do on Node). The existing fs.watch -> rebuild (route table, elision) and SSE -> browser reload stay and complement it: --hot re-evals the server module, fs.watch re-derives the analysis and refreshes the browser.

Detection: auto, no opt-in flag

Earlier I assumed webjs dev runs on Node even under bun --bun run dev (because the scaffold dev script is concurrently "npm:css:watch" "npm:webjs:dev", and I expected the npm run hop to reset to Node). That is WRONG. Tested with a node-shebang probe through the exact bun --bun run dev -> concurrently -> npm:probe chain: it ran under bun 1.3.14. The --bun flag puts a node->bun shim on PATH for the whole process tree, so even npm run grandchildren hitting a #!/usr/bin/env node shebang (the webjs bin) run under Bun.

So webjs dev genuinely runs under Bun when invoked via bun --bun run dev, which means the CLI can just auto-detect process.versions.bun and re-exec under bun --hot. No --bun / WEBJS_BUN opt-in needed. The user runs bun --bun run dev exactly as the docs already say and gets hot-reload. A --no-hot escape hatch is reasonable to keep.

Why this is the right model

• Remix 3 (the only other no-build framework) uses full process restart (bun --watch / node --watch): runtime-agnostic but reboots on every edit (drops WS, in-memory state). bun --hot is strictly better (in-place re-eval, no reboot).
• Next / Nuxt / TanStack / Astro all run dev on Node through a bundler dev runtime (Vite module runner / webpack require.cache) and only DEPLOY to Bun. None do Bun-native dev at all. So this makes webjs the only framework with no-build, runtime-native, hot-reloading Bun dev.

Implementation surface

• packages/cli dev launcher: where it spawns node --watch <self> on Node, add a Bun branch spawning bun --hot <self> (gated on process.versions.bun, with a --no-hot override).
• App package.json scripts stay untouched (the intelligence lives in the one CLI command, reached under Bun via bun --bun run dev).
• Prod is unaffected: prod re-imports nothing (every ?t= site is dev ? ... : ''), so a Bun prod deploy has no reload concern.

To verify end-to-end (acceptance)

• On Bun dev, editing a route.ts / page.ts / .server.ts is reflected on the next request without a restart (parity with Node dev).
• The dev-server process stays up across an app-module edit: the SSE channel + any open WS connections survive (app modules are dynamically imported, so --hot invalidates only that module, not the entry).
• A framework-file edit (a static import of the entry) degrades gracefully (re-runs more of the graph, or falls back to restart).
• A cross-runtime test under test/bun/ proving the server-module reload on Bun.