Merge branch 'fix-memory-errors-in-dev'

dist/commands/dev/index.js

@@ -4,9 +4,8 @@ import grabDirNames from "../../utils/grab-dir-names";
 import writeErrorFile from "../../functions/write-error-file";
 import { existsSync, rmSync } from "fs";
 const { BUNDLER_CTX_MAP_JSON, SSR_BUNDLER_CTX_MAP_JSON, BUNX_BUNDLER_ERROR_EXIT_FILE, } = grabDirNames();
-let retries = 0;
-let timeout;
 const MAX_RETRIES = 5;
+const RETRY_RESET_AFTER_MS = 10000;
 export default function () {
     return new Command("dev")
         .description("Run development server")
@@ -24,7 +23,10 @@ export default function () {
     });
 }
 async function dev() {
-    clearTimeout(timeout);
+    // A loop, not recursion: each restart would otherwise keep the previous
+    // call (and its subprocess) alive for the supervisor's whole lifetime.
+    let retries = 0;
+    while (true) {
         if (retries >= MAX_RETRIES) {
             console.error(`Dev server crashed ${MAX_RETRIES} times. Exiting.`);
             process.exit(1);
@@ -45,30 +47,26 @@ async function dev() {
                 NODE_ENV: "development",
             },
         };
-    let dev_process;
+        const started_at = Date.now();
+        let child_process;
         try {
-        dev_process = Bun.spawn(spawn_options);
+            child_process = Bun.spawn(spawn_options);
         }
         catch (error) {
             console.error(`Failed to start dev process:`, error);
             retries++;
-        timeout = setTimeout(() => {
+            continue;
-            retries = 0;
-        }, 10000);
-        return await dev();
         }
-    const exited = await dev_process.exited;
+        const exited = await child_process.exited;
-    // Restart on any numeric exit (0 included: the server should never exit
+        // A null exit means the child was killed by a signal (e.g. Ctrl+C
-    // cleanly). A null exit means the child was killed by a signal (e.g.
+        // in the shared terminal), which we must not restart.
-    // Ctrl+C in the shared terminal), which we must not restart.
+        if (exited == null) {
-    if (exited != null) {
+            return;
-        retries++;
+        }
-        timeout = setTimeout(() => {
+        // Restart on any numeric exit (0 included: the server should never
-            retries = 0;
+        // exit cleanly). Only consecutive quick crashes count toward the
-        }, 10000);
+        // limit; a child that ran for a while starts the count over.
-        return await dev();
+        retries =
+            Date.now() - started_at >= RETRY_RESET_AFTER_MS ? 1 : retries + 1;
     }
-    timeout = setTimeout(() => {
-        retries = 0;
-    }, 10000);
 }

dist/commands/start/index.js

@@ -4,9 +4,8 @@ import writeErrorFile from "../../functions/write-error-file";
 import grabDirNames from "../../utils/grab-dir-names";
 import { existsSync, rmSync } from "fs";
 const { BUNX_BUNDLER_ERROR_EXIT_FILE } = grabDirNames();
-let retries = 0;
-let timeout;
 const MAX_RETRIES = 5;
+const RETRY_RESET_AFTER_MS = 10000;
 export default function () {
     return new Command("start")
         .description("Start production server")
@@ -18,7 +17,10 @@ export default function () {
     });
 }
 async function start() {
-    clearTimeout(timeout);
+    // A loop, not recursion: each restart would otherwise keep the previous
+    // call (and its subprocess) alive for the supervisor's whole lifetime.
+    let retries = 0;
+    while (true) {
         if (retries >= MAX_RETRIES) {
             console.error(`Production server crashed ${MAX_RETRIES} times. Exiting.`);
             process.exit(1);
@@ -39,29 +41,26 @@ async function start() {
                 NODE_ENV: "production",
             },
         };
-    let dev_process;
+        const started_at = Date.now();
+        let child_process;
         try {
-        dev_process = Bun.spawn(spawn_options);
+            child_process = Bun.spawn(spawn_options);
         }
         catch (error) {
             console.error(`Failed to start production process:`, error);
             retries++;
-        timeout = setTimeout(() => {
+            continue;
-            retries = 0;
-        }, 10000);
-        return await start();
         }
-    const exited = await dev_process.exited;
+        const exited = await child_process.exited;
-    // Restart on any numeric exit (0 included). A null exit means the child
+        // A null exit means the child was killed by a signal (e.g. Ctrl+C
-    // was killed by a signal, which we must not restart.
+        // in the shared terminal), which we must not restart.
-    if (exited != null) {
+        if (exited == null) {
-        retries++;
+            return;
-        timeout = setTimeout(() => {
+        }
-            retries = 0;
+        // Restart on any numeric exit (0 included: the server should never
-        }, 10000);
+        // exit cleanly). Only consecutive quick crashes count toward the
-        return await start();
+        // limit; a child that ran for a while starts the count over.
+        retries =
+            Date.now() - started_at >= RETRY_RESET_AFTER_MS ? 1 : retries + 1;
     }
-    timeout = setTimeout(() => {
-        retries = 0;
-    }, 10000);
 }

dist/data/app-data.d.ts

@@ -8,4 +8,5 @@ export declare const AppData: {
     readonly BunextTmpFileExt: ".bunext_tmp.tsx";
     readonly BunextHMRRetryRoute: "/.bunext/hmr-retry";
     readonly DefaultMaxLogs: 50;
+    readonly DefaultSSRRenderTimeoutMs: 30000;
 };

dist/data/app-data.js

@@ -8,4 +8,5 @@ export const AppData = {
     BunextTmpFileExt: ".bunext_tmp.tsx",
     BunextHMRRetryRoute: "/.bunext/hmr-retry",
     DefaultMaxLogs: 50,
+    DefaultSSRRenderTimeoutMs: 30000,
 };

dist/functions/bundler/dispose-bundler-contexts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Disposes the hydration and SSR esbuild contexts, releasing the incremental
+ * build state esbuild keeps in memory for them. The bundlers re-create the
+ * contexts on their next run.
+ */
+export default function disposeBundlerContexts(): Promise<void>;

dist/functions/bundler/dispose-bundler-contexts.js

@@ -0,0 +1,17 @@
+/**
+ * Disposes the hydration and SSR esbuild contexts, releasing the incremental
+ * build state esbuild keeps in memory for them. The bundlers re-create the
+ * contexts on their next run.
+ */
+export default async function disposeBundlerContexts() {
+    try {
+        await global.BUNEXT_BUNDLER_CTX?.dispose();
+    }
+    catch (error) { }
+    global.BUNEXT_BUNDLER_CTX = undefined;
+    try {
+        await global.BUNEXT_SSR_BUNDLER_CTX?.dispose();
+    }
+    catch (error) { }
+    global.BUNEXT_SSR_BUNDLER_CTX = undefined;
+}

dist/functions/bundler/pages-ssr-context-bundler.js

@@ -8,6 +8,7 @@ import grabRootFilePath from "../server/web-pages/grab-root-file-path";
 import ssrVirtualFilesPlugin from "./plugins/ssr-virtual-files-plugin";
 import ssrCTXArtifactTracker from "./plugins/ssr-ctx-artifact-tracker";
 import cleanupArtifacts from "../server/cleanup-artifacts";
+import { evictDeletedModules } from "../../utils/import-fresh";
 import { writeFileSync } from "fs";
 import path from "path";
 import { log } from "../../utils/log";
@@ -165,6 +166,9 @@ async function doSSRRebuild(params) {
         global.BUNEXT_SSR_BUNDLER_CTX_DISPOSED = false;
         global.BUNEXT_BUILD_FAILED = false;
         await cleanupArtifacts({ paradigm: "ssr" });
+        // esbuild has now replaced superseded outputs on disk; release the
+        // ones the server already imported.
+        evictDeletedModules(BUNX_CWD_MODULE_CACHE_DIR);
     }
     catch (error) {
         global.BUNEXT_SSR_BUNDLER_CTX_DISPOSED = true;

dist/functions/bunext-init.js

@@ -8,6 +8,7 @@ import serverPostBuildFn from "./server/server-post-build-fn";
 import reactModulesBundler from "./bundler/react-modules-bundler";
 import grabConstants from "../utils/grab-constants";
 import watcherEsbuildCTX from "./server/watcher-esbuild-ctx";
+import disposeBundlerContexts from "./bundler/dispose-bundler-contexts";
 import { readFileSync } from "fs";
 const dirNames = grabDirNames();
 const { PAGES_DIR, BUNDLER_CTX_MAP_JSON, SSR_BUNDLER_CTX_MAP_JSON } = dirNames;
@@ -86,6 +87,9 @@ export default async function bunextInit(params) {
         else {
             log.build(`Building Modules ...`);
             await allPagesESBuildContextBundler({ start: true });
+            // The server only needs the artifact maps; don't keep
+            // esbuild's build state alive for the rest of the process.
+            await disposeBundlerContexts();
         }
         cron();
     }

dist/functions/server/bunext-req-handler.js

@@ -16,15 +16,19 @@ const HMR_RETRY_COOLDOWN_MS = 5000;
 let lastHmrRetryTime = 0;
 export default async function bunextRequestHandler({ req: initial_req, server, }) {
     const is_dev = isDevelopment();
-    let req = initial_req.clone();
+    const middleware = global.BUNEXT_CONSTANTS.config?.middleware;
+    // Middleware may consume `initial_req`'s body, so it gets its own copy.
+    // Cloning tees the body stream and buffers whatever one side doesn't
+    // read, so only pay for it when middleware is configured.
+    let req = middleware ? initial_req.clone() : initial_req;
     try {
         let url = new URL(req.url);
         if (checkExcludedPatterns({ path: url.pathname })) {
             return Response.json({ success: false, msg: `Invalid Path` }, { status: 404 });
         }
         let response = undefined;
-        if (global.BUNEXT_CONSTANTS.config?.middleware) {
+        if (middleware) {
-            const middleware_res = await global.BUNEXT_CONSTANTS.config.middleware({
+            const middleware_res = await middleware({
                 req: initial_req,
                 url,
             });

dist/functions/server/full-rebuild.js

@@ -3,6 +3,8 @@ import allPagesESBuildContextBundler from "../bundler/all-pages-esbuild-context-
 import serverPostBuildFn from "./server-post-build-fn";
 import { restartWatcher } from "./watcher-esbuild-ctx";
 import { logBuildErrorsOnce } from "../../utils/build-error-log";
+import disposeBundlerContexts from "../bundler/dispose-bundler-contexts";
+import isDevelopment from "../../utils/is-development";
 // Single-flight: error recovery paths (grab-page-component retries, the
 // watcher, post-build HMR pushes) all call fullRebuild, and each rebuild
 // triggers serverPostBuildFn which can re-enter error handling. Without this
@@ -33,18 +35,17 @@ async function doFullRebuild(params) {
             log.watch(msg);
         }
         global.BUNEXT_ROUTER.reload();
-        try {
+        await disposeBundlerContexts();
-            await global.BUNEXT_BUNDLER_CTX?.dispose();
-            global.BUNEXT_BUNDLER_CTX = undefined;
-            await global.BUNEXT_SSR_BUNDLER_CTX?.dispose();
-            global.BUNEXT_SSR_BUNDLER_CTX = undefined;
-        }
-        catch (error) { }
         await allPagesESBuildContextBundler({
             post_build_fn: async (params) => {
                 await serverPostBuildFn(params);
             },
         });
+        // Production never rebuilds incrementally; don't keep esbuild's
+        // build state alive for the rest of the process.
+        if (!isDevelopment()) {
+            await disposeBundlerContexts();
+        }
     }
     catch (error) {
         logBuildErrorsOnce([{ text: error?.message || String(error) }], (line) => log.error(line));

dist/functions/server/handle-routes.js

@@ -8,6 +8,7 @@ import path from "path";
 import grabDirNames from "../../utils/grab-dir-names";
 import grabRelativePath from "../../utils/grab-relative-path";
 import { RequestBodyTooLargeError } from "../../utils/read-request-body";
+import importFresh from "../../utils/import-fresh";
 const { ROOT_DIR } = grabDirNames();
 export default async function ({ req }) {
     try {
@@ -29,18 +30,14 @@ export default async function ({ req }) {
             });
         }
         let module;
-        const now = Date.now();
         const relative_match_path = grabRelativePath(match.filePath);
         if (is_dev &&
             global.BUNEXT_SSR_BUNDLER_CTX_MAP?.[relative_match_path]?.path) {
             const target_import = path.join(ROOT_DIR, global.BUNEXT_SSR_BUNDLER_CTX_MAP[relative_match_path].path);
-            module = await import(`${target_import}?t=${now}`);
+            module = await importFresh(target_import);
         }
         else {
-            const import_path = is_dev
+            module = await importFresh(match.filePath);
-                ? `${match.filePath}?t=${now}`
-                : match.filePath;
-            module = await import(import_path);
         }
         const config = module.config;
         const maxBodyBytes = config?.max_request_body_mb

dist/functions/server/start-server.js

@@ -2,7 +2,7 @@ import _ from "lodash";
 import { log } from "../../utils/log";
 import serverParamsGen from "./server-params-gen";
 import isDevelopment from "../../utils/is-development";
-import { restartWatcher, watcherRestartAvailable, } from "./watcher-esbuild-ctx";
+import { watcherWatchdogTick } from "./watcher-esbuild-ctx";
 export default async function startServer() {
     const serverParams = await serverParamsGen();
     const server = Bun.serve(serverParams);
@@ -10,15 +10,9 @@ export default async function startServer() {
     global.BUNEXT_SERVER = server;
     log.server(`http://${server.hostname}:${server.port}`);
     if (is_dev) {
-        // Watchdog: periodically re-create the FS watcher in case it went
+        // Watchdog: re-create the FS watcher if it went stale and stopped
-        // stale and stopped receiving events. Skipped while a recent restart
+        // receiving events.
-        // (e.g. by fullRebuild) is still fresh so the watcher isn't churned
+        setInterval(watcherWatchdogTick, 5000);
-        // twice in a row.
-        setInterval(() => {
-            if (watcherRestartAvailable()) {
-                restartWatcher();
-            }
-        }, 5000);
     }
     return server;
 }

dist/functions/server/watcher-esbuild-ctx.d.ts

@@ -5,10 +5,12 @@
  */
 export declare function restartWatcher(): void;
 /**
- * True when the watcher was last (re)created long enough ago that the
+ * Called periodically by the dev server. Re-creates the watcher only when it
- * watchdog should consider re-creating it again.
+ * failed to report the probe written on the previous tick, i.e. when it went
+ * stale. A healthy watcher is left alone: re-creating it rescans the whole
+ * project tree.
  */
-export declare function watcherRestartAvailable(): boolean;
+export declare function watcherWatchdogTick(): void;
 export default function watcherEsbuildCTX(params?: {
     pages_snapshot?: string;
 }): Promise<void>;

dist/functions/server/watcher-esbuild-ctx.js

@@ -1,6 +1,6 @@
 import chokidar from "chokidar";
 import path from "path";
-import { existsSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
 import grabDirNames from "../../utils/grab-dir-names";
 import fullRebuild from "./full-rebuild";
 import { AppData } from "../../data/app-data";
@@ -10,10 +10,18 @@ import grabAllPages from "../../utils/grab-all-pages";
 import serverPostBuildFn from "./server-post-build-fn";
 import { log } from "../../utils/log";
 import { logBuildErrorsOnce } from "../../utils/build-error-log";
-const { ROOT_DIR, BUNX_BUNDLER_ERROR_EXIT_FILE } = grabDirNames();
+const { ROOT_DIR, BUNX_CWD_DIR, BUNX_BUNDLER_ERROR_EXIT_FILE } = grabDirNames();
-// Tracks the last watcher re-creation so the 5s watchdog in start-server
+// The watchdog writes this file and expects the watcher to report it. It
-// doesn't fight fullRebuild (which also restarts the watcher after a rebuild).
+// sits under `.bunext` (otherwise ignored), so only this path is watched.
+const WATCH_PROBE_DIR = path.join(BUNX_CWD_DIR, "watch-probe");
+const WATCH_PROBE_FILE = path.join(WATCH_PROBE_DIR, "probe");
+// Dedupes near-simultaneous restarts (fullRebuild, watchdog).
 let last_watcher_restart = 0;
+// The current watcher finished its initial scan; probes written before
+// that may not produce events.
+let watcher_ready = false;
+// A probe was written and the watcher hasn't reported it yet.
+let probe_pending = false;
 /**
  * Closes and re-creates the FS watcher. Deduped: callers that restart the
  * watcher around the same time (fullRebuild, reloadWatcher, watchdog) only
@@ -48,11 +56,27 @@ function grabPagesSnapshot() {
     }
 }
 /**
- * True when the watcher was last (re)created long enough ago that the
+ * Called periodically by the dev server. Re-creates the watcher only when it
- * watchdog should consider re-creating it again.
+ * failed to report the probe written on the previous tick, i.e. when it went
+ * stale. A healthy watcher is left alone: re-creating it rescans the whole
+ * project tree.
  */
-export function watcherRestartAvailable() {
+export function watcherWatchdogTick() {
-    return Date.now() - last_watcher_restart > 6000;
+    if (!global.BUNEXT_PAGES_SRC_WATCHER || !watcher_ready)
+        return;
+    if (probe_pending) {
+        restartWatcher();
+        return;
+    }
+    try {
+        mkdirSync(WATCH_PROBE_DIR, { recursive: true });
+        writeFileSync(WATCH_PROBE_FILE, String(Date.now()));
+        probe_pending = true;
+    }
+    catch (error) { }
+}
+function isWatchProbePath(p) {
+    return (p === WATCH_PROBE_FILE || p === WATCH_PROBE_DIR || p === BUNX_CWD_DIR);
 }
 const TARGET_FILES_MATCH = /\.(tsx?|jsx?|css)$/;
 // Rebuild coalescing: editors emit bursts of events per save (change +
@@ -170,10 +194,10 @@ function isPathExcluded(filename, full_file_path) {
 // install watches (and deliver events) for trees the bundler never reads.
 function buildIgnoredPatterns() {
     const ignored = [
-        /(^|[\/\\])\../,
+        (p) => !isWatchProbePath(p) && /(^|[\/\\])\../.test(p),
         /(^|[\/\\])node_modules([\/\\]|$)/,
         /(^|[\/\\])public([\/\\]|$)/,
-        /(^|[\/\\])\.bunext([\/\\]|$)/,
+        (p) => !isWatchProbePath(p) && /(^|[\/\\])\.bunext([\/\\]|$)/.test(p),
         /(^|[\/\\])\.git([\/\\]|$)/,
         /(^|[\/\\])dist([\/\\]|$)/,
         /bun\.lockb$/,
@@ -195,6 +219,12 @@ function buildIgnoredPatterns() {
     return ignored;
 }
 export default async function watcherEsbuildCTX(params) {
+    try {
+        mkdirSync(WATCH_PROBE_DIR, { recursive: true });
+    }
+    catch (error) { }
+    watcher_ready = false;
+    probe_pending = false;
     const pages_src_watcher = chokidar.watch(ROOT_DIR, {
         ignored: buildIgnoredPatterns(),
         persistent: true,
@@ -202,18 +232,27 @@ export default async function watcherEsbuildCTX(params) {
     });
     watcherHandlers(pages_src_watcher, (event, filePath) => handleEvent(event, filePath));
     const pages_snapshot = params?.pages_snapshot;
-    if (pages_snapshot !== undefined) {
     pages_src_watcher.on("ready", () => {
+        if (global.BUNEXT_PAGES_SRC_WATCHER === pages_src_watcher) {
+            watcher_ready = true;
+        }
+        if (pages_snapshot === undefined)
+            return;
         const current = grabPagesSnapshot();
         if (current !== undefined && current !== pages_snapshot) {
             pending_structural = true;
             scheduleRebuild();
         }
     });
-    }
     global.BUNEXT_PAGES_SRC_WATCHER = pages_src_watcher;
 }
 function handleEvent(event, filePath) {
+    if (isWatchProbePath(filePath)) {
+        if (filePath === WATCH_PROBE_FILE) {
+            probe_pending = false;
+        }
+        return;
+    }
     try {
         const filename = path.relative(ROOT_DIR, filePath);
         const full_file_path = filePath;

dist/functions/server/web-pages/generate-web-html.js

@@ -77,8 +77,16 @@ export default async function genWebHTML({ component: Main, pageProps, bundledMa
     let htmlBody;
     let render_error;
     let has_render_error = false;
+    const render_timeout_ms = global.BUNEXT_CONFIG.ssr_render_timeout_ms ||
+        AppData["DefaultSSRRenderTimeoutMs"];
+    // Without a deadline, a Suspense boundary that never settles keeps the
+    // request (and its whole render tree) alive forever. The timer is
+    // cleared once the render ends so finished requests don't linger.
+    const render_abort = new AbortController();
+    const render_timeout = setTimeout(() => render_abort.abort(new RenderTimeoutError(`Page render timed out after ${render_timeout_ms}ms`)), render_timeout_ms);
     try {
         const stream = await renderToReadableStream(final_component, {
+            signal: render_abort.signal,
             onError(error) {
                 if (error?.message?.includes('unique "key" prop'))
                     return;
@@ -86,12 +94,16 @@ export default async function genWebHTML({ component: Main, pageProps, bundledMa
                     has_render_error = true;
                     render_error = error;
                 }
+                // A timeout has no useful stack; it's logged upstream.
+                if (!(error instanceof RenderTimeoutError)) {
                     original_console.error(error);
+                }
             },
         });
         htmlBody = await new Response(stream).text();
     }
     finally {
+        clearTimeout(render_timeout);
         restoreConsole();
     }
     // A component crash during SSR must surface as a proper error (handled
@@ -103,6 +115,8 @@ export default async function genWebHTML({ component: Main, pageProps, bundledMa
     html += htmlBody;
     return html;
 }
+class RenderTimeoutError extends Error {
+}
 let original_console = console;
 let silenced_renders = 0;
 /**

dist/functions/server/web-pages/grab-file-path-module.d.ts

@@ -1,6 +0,0 @@
-type Params = {
-    file_path: string;
-    out_file?: string;
-};
-export default function grabFilePathModule<T extends any = any>({ file_path, out_file, }: Params): Promise<T>;
-export {};

dist/functions/server/web-pages/grab-file-path-module.js

@@ -1,30 +0,0 @@
-import isDevelopment from "../../../utils/is-development";
-import * as esbuild from "esbuild";
-import grabDirNames from "../../../utils/grab-dir-names";
-import path from "path";
-import tailwindEsbuildPlugin from "./tailwind-esbuild-plugin";
-export default async function grabFilePathModule({ file_path, out_file, }) {
-    const dev = isDevelopment();
-    const { BUNX_CWD_MODULE_CACHE_DIR } = grabDirNames();
-    const target_cache_file_path = out_file ||
-        path.join(BUNX_CWD_MODULE_CACHE_DIR, `${path.basename(file_path)}.js`);
-    await esbuild.build({
-        entryPoints: [file_path],
-        bundle: true,
-        format: "esm",
-        target: "es2020",
-        platform: "node",
-        // external: ["react", "react-dom"],
-        minify: true,
-        define: {
-            "process.env.NODE_ENV": JSON.stringify(dev ? "development" : "production"),
-        },
-        metafile: true,
-        plugins: [tailwindEsbuildPlugin],
-        jsx: "automatic",
-        outfile: target_cache_file_path,
-    });
-    // Loader.registry.delete(target_cache_file_path);
-    const module = await import(`${target_cache_file_path}?t=${Date.now()}`);
-    return module;
-}

dist/types/index.d.ts

@@ -109,6 +109,11 @@ export type BunextConfig = {
      * `/robots.txt` disallows all crawlers regardless of `public/robots.txt`.
      */
     disable_seo?: boolean;
+    /**
+     * Maximum time (ms) a page's server render may take before it is
+     * aborted and answered with a 500. Defaults to 30000.
+     */
+    ssr_render_timeout_ms?: number;
 };
 export type BunextConfigMiddlewareParams = {
     req: Request;

dist/utils/import-fresh.d.ts

@@ -1,7 +1,24 @@
 /**
- * Dev: bypass Bun's module registry so rebuilt files are picked up.
+ * Imports a module by its stable path.
- * Prod: import by stable path so each module is loaded (and kept) once.
+ *
- * A unique `?t=` per call creates a new, never-evicted module record, so
+ * Dev: when the file changed since it was last imported, its registry
- * using it in production leaks memory on every request.
+ * entry is evicted first so the new version is evaluated and the old one
+ * can be garbage collected. A cache-busting `?t=` query would instead
+ * create a new, never-evicted module record on every call.
+ *
+ * Prod: plain import, so each module is loaded (and kept) once.
  */
 export default function importFresh<T = any>(file_path: string): Promise<T>;
+/**
+ * Drops a module from Bun's registry so its memory can be reclaimed and the
+ * next import re-evaluates it. Only the module itself is evicted, not the
+ * modules it imports.
+ */
+export declare function evictModule(file_path: string): void;
+/**
+ * Evicts every registry entry under `dir` whose file no longer exists. Bundle
+ * outputs (entries and shared chunks) are content-hashed and esbuild deletes
+ * the superseded ones on rebuild, so a missing file means no current module
+ * imports it anymore.
+ */
+export declare function evictDeletedModules(dir: string): void;

dist/utils/import-fresh.js

@@ -1,10 +1,65 @@
+import { existsSync, statSync } from "fs";
+import path from "path";
 import isDevelopment from "./is-development";
 /**
- * Dev: bypass Bun's module registry so rebuilt files are picked up.
+ * File path -> mtime of the version currently held in Bun's module
- * Prod: import by stable path so each module is loaded (and kept) once.
+ * registry (dev only).
- * A unique `?t=` per call creates a new, never-evicted module record, so
- * using it in production leaks memory on every request.
  */
-export default function importFresh(file_path) {
+const loaded_versions = new Map();
-    return import(isDevelopment() ? `${file_path}?t=${Date.now()}` : file_path);
+/**
+ * Imports a module by its stable path.
+ *
+ * Dev: when the file changed since it was last imported, its registry
+ * entry is evicted first so the new version is evaluated and the old one
+ * can be garbage collected. A cache-busting `?t=` query would instead
+ * create a new, never-evicted module record on every call.
+ *
+ * Prod: plain import, so each module is loaded (and kept) once.
+ */
+export default async function importFresh(file_path) {
+    if (!isDevelopment()) {
+        return import(file_path);
+    }
+    let mtime;
+    try {
+        mtime = statSync(file_path).mtimeMs;
+    }
+    catch { }
+    if (loaded_versions.has(file_path) &&
+        loaded_versions.get(file_path) !== mtime) {
+        evictModule(file_path);
+    }
+    try {
+        const mod = await import(file_path);
+        loaded_versions.set(file_path, mtime);
+        return mod;
+    }
+    catch (error) {
+        // Don't keep a failed evaluation around: the next request retries.
+        evictModule(file_path);
+        throw error;
+    }
+}
+/**
+ * Drops a module from Bun's registry so its memory can be reclaimed and the
+ * next import re-evaluates it. Only the module itself is evicted, not the
+ * modules it imports.
+ */
+export function evictModule(file_path) {
+    delete require.cache[file_path];
+    loaded_versions.delete(file_path);
+}
+/**
+ * Evicts every registry entry under `dir` whose file no longer exists. Bundle
+ * outputs (entries and shared chunks) are content-hashed and esbuild deletes
+ * the superseded ones on rebuild, so a missing file means no current module
+ * imports it anymore.
+ */
+export function evictDeletedModules(dir) {
+    const prefix = dir.endsWith(path.sep) ? dir : dir + path.sep;
+    for (const key of Object.keys(require.cache)) {
+        if (key.startsWith(prefix) && !existsSync(key)) {
+            evictModule(key);
+        }
+    }
 }

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@moduletrace/bunext",
-    "version": "1.3.1",
+    "version": "1.2.4",
     "main": "dist/index.js",
     "module": "index.ts",
     "dependencies": {

src/commands/dev/index.ts

@@ -11,9 +11,8 @@ const {
     BUNX_BUNDLER_ERROR_EXIT_FILE,
 } = grabDirNames();
 
-let retries = 0;
-let timeout: any;
 const MAX_RETRIES = 5;
+const RETRY_RESET_AFTER_MS = 10000;
 
 export default function () {
     return new Command("dev")
@@ -33,8 +32,11 @@ export default function () {
 }
 
 async function dev() {
-    clearTimeout(timeout);
+    // A loop, not recursion: each restart would otherwise keep the previous
+    // call (and its subprocess) alive for the supervisor's whole lifetime.
+    let retries = 0;
 
+    while (true) {
         if (retries >= MAX_RETRIES) {
             console.error(`Dev server crashed ${MAX_RETRIES} times. Exiting.`);
             process.exit(1);
@@ -59,32 +61,29 @@ async function dev() {
             },
         };
 
-    let dev_process;
+        const started_at = Date.now();
+
+        let child_process;
         try {
-        dev_process = Bun.spawn(spawn_options);
+            child_process = Bun.spawn(spawn_options);
         } catch (error) {
             console.error(`Failed to start dev process:`, error);
             retries++;
-        timeout = setTimeout(() => {
+            continue;
-            retries = 0;
-        }, 10000);
-        return await dev();
         }
 
-    const exited = await dev_process.exited;
+        const exited = await child_process.exited;
 
-    // Restart on any numeric exit (0 included: the server should never exit
+        // A null exit means the child was killed by a signal (e.g. Ctrl+C
-    // cleanly). A null exit means the child was killed by a signal (e.g.
+        // in the shared terminal), which we must not restart.
-    // Ctrl+C in the shared terminal), which we must not restart.
+        if (exited == null) {
-    if (exited != null) {
+            return;
-        retries++;
-        timeout = setTimeout(() => {
-            retries = 0;
-        }, 10000);
-        return await dev();
         }
 
-    timeout = setTimeout(() => {
+        // Restart on any numeric exit (0 included: the server should never
-        retries = 0;
+        // exit cleanly). Only consecutive quick crashes count toward the
-    }, 10000);
+        // limit; a child that ran for a while starts the count over.
+        retries =
+            Date.now() - started_at >= RETRY_RESET_AFTER_MS ? 1 : retries + 1;
+    }
 }

src/commands/start/index.ts

@@ -7,9 +7,8 @@ import { existsSync, rmSync } from "fs";
 
 const { BUNX_BUNDLER_ERROR_EXIT_FILE } = grabDirNames();
 
-let retries = 0;
-let timeout: any;
 const MAX_RETRIES = 5;
+const RETRY_RESET_AFTER_MS = 10000;
 
 export default function () {
     return new Command("start")
@@ -24,8 +23,11 @@ export default function () {
 }
 
 async function start() {
-    clearTimeout(timeout);
+    // A loop, not recursion: each restart would otherwise keep the previous
+    // call (and its subprocess) alive for the supervisor's whole lifetime.
+    let retries = 0;
 
+    while (true) {
         if (retries >= MAX_RETRIES) {
             console.error(
                 `Production server crashed ${MAX_RETRIES} times. Exiting.`,
@@ -52,31 +54,29 @@ async function start() {
             },
         };
 
-    let dev_process;
+        const started_at = Date.now();
+
+        let child_process;
         try {
-        dev_process = Bun.spawn(spawn_options);
+            child_process = Bun.spawn(spawn_options);
         } catch (error) {
             console.error(`Failed to start production process:`, error);
             retries++;
-        timeout = setTimeout(() => {
+            continue;
-            retries = 0;
-        }, 10000);
-        return await start();
         }
 
-    const exited = await dev_process.exited;
+        const exited = await child_process.exited;
 
-    // Restart on any numeric exit (0 included). A null exit means the child
+        // A null exit means the child was killed by a signal (e.g. Ctrl+C
-    // was killed by a signal, which we must not restart.
+        // in the shared terminal), which we must not restart.
-    if (exited != null) {
+        if (exited == null) {
-        retries++;
+            return;
-        timeout = setTimeout(() => {
-            retries = 0;
-        }, 10000);
-        return await start();
         }
 
-    timeout = setTimeout(() => {
+        // Restart on any numeric exit (0 included: the server should never
-        retries = 0;
+        // exit cleanly). Only consecutive quick crashes count toward the
-    }, 10000);
+        // limit; a child that ran for a while starts the count over.
+        retries =
+            Date.now() - started_at >= RETRY_RESET_AFTER_MS ? 1 : retries + 1;
+    }
 }

src/data/app-data.ts

@@ -8,4 +8,5 @@ export const AppData = {
     BunextTmpFileExt: ".bunext_tmp.tsx",
     BunextHMRRetryRoute: "/.bunext/hmr-retry",
     DefaultMaxLogs: 50,
+    DefaultSSRRenderTimeoutMs: 30000,
 } as const;

src/functions/bundler/dispose-bundler-contexts.ts

@@ -0,0 +1,16 @@
+/**
+ * Disposes the hydration and SSR esbuild contexts, releasing the incremental
+ * build state esbuild keeps in memory for them. The bundlers re-create the
+ * contexts on their next run.
+ */
+export default async function disposeBundlerContexts() {
+    try {
+        await global.BUNEXT_BUNDLER_CTX?.dispose();
+    } catch (error) {}
+    global.BUNEXT_BUNDLER_CTX = undefined;
+
+    try {
+        await global.BUNEXT_SSR_BUNDLER_CTX?.dispose();
+    } catch (error) {}
+    global.BUNEXT_SSR_BUNDLER_CTX = undefined;
+}

src/functions/bundler/pages-ssr-context-bundler.ts

@@ -9,6 +9,7 @@ import grabRootFilePath from "../server/web-pages/grab-root-file-path";
 import ssrVirtualFilesPlugin from "./plugins/ssr-virtual-files-plugin";
 import ssrCTXArtifactTracker from "./plugins/ssr-ctx-artifact-tracker";
 import cleanupArtifacts from "../server/cleanup-artifacts";
+import { evictDeletedModules } from "../../utils/import-fresh";
 import { writeFileSync } from "fs";
 import path from "path";
 import { log } from "../../utils/log";
@@ -220,6 +221,10 @@ async function doSSRRebuild(params?: RebuildParams) {
         global.BUNEXT_BUILD_FAILED = false;
 
         await cleanupArtifacts({ paradigm: "ssr" });
+
+        // esbuild has now replaced superseded outputs on disk; release the
+        // ones the server already imported.
+        evictDeletedModules(BUNX_CWD_MODULE_CACHE_DIR);
     } catch (error: any) {
         global.BUNEXT_SSR_BUNDLER_CTX_DISPOSED = true;
         global.BUNEXT_BUILD_FAILED = true;

src/functions/bunext-init.ts

@@ -16,6 +16,7 @@ import serverPostBuildFn from "./server/server-post-build-fn";
 import reactModulesBundler from "./bundler/react-modules-bundler";
 import grabConstants from "../utils/grab-constants";
 import watcherEsbuildCTX from "./server/watcher-esbuild-ctx";
+import disposeBundlerContexts from "./bundler/dispose-bundler-contexts";
 import { readFileSync } from "fs";
 
 /**
@@ -162,6 +163,9 @@ export default async function bunextInit(params?: Params) {
         } else {
             log.build(`Building Modules ...`);
             await allPagesESBuildContextBundler({ start: true });
+            // The server only needs the artifact maps; don't keep
+            // esbuild's build state alive for the rest of the process.
+            await disposeBundlerContexts();
         }
 
         cron();

src/functions/server/bunext-req-handler.ts

@@ -26,7 +26,12 @@ export default async function bunextRequestHandler({
     server,
 }: Params): Promise<Response> {
     const is_dev = isDevelopment();
-    let req = initial_req.clone();
+    const middleware = global.BUNEXT_CONSTANTS.config?.middleware;
+
+    // Middleware may consume `initial_req`'s body, so it gets its own copy.
+    // Cloning tees the body stream and buffers whatever one side doesn't
+    // read, so only pay for it when middleware is configured.
+    let req = middleware ? initial_req.clone() : initial_req;
 
     try {
         let url = new URL(req.url);
@@ -40,9 +45,8 @@ export default async function bunextRequestHandler({
 
         let response: Response | undefined = undefined;
 
-        if (global.BUNEXT_CONSTANTS.config?.middleware) {
+        if (middleware) {
-            const middleware_res =
+            const middleware_res = await middleware({
-                await global.BUNEXT_CONSTANTS.config.middleware({
                 req: initial_req,
                 url,
             });

src/functions/server/full-rebuild.ts

@@ -3,6 +3,8 @@ import allPagesESBuildContextBundler from "../bundler/all-pages-esbuild-context-
 import serverPostBuildFn from "./server-post-build-fn";
 import { restartWatcher } from "./watcher-esbuild-ctx";
 import { logBuildErrorsOnce } from "../../utils/build-error-log";
+import disposeBundlerContexts from "../bundler/dispose-bundler-contexts";
+import isDevelopment from "../../utils/is-development";
 
 // Single-flight: error recovery paths (grab-page-component retries, the
 // watcher, post-build HMR pushes) all call fullRebuild, and each rebuild
@@ -42,19 +44,19 @@ async function doFullRebuild(params?: { msg?: string }) {
 
         global.BUNEXT_ROUTER.reload();
 
-        try {
+        await disposeBundlerContexts();
-            await global.BUNEXT_BUNDLER_CTX?.dispose();
-            global.BUNEXT_BUNDLER_CTX = undefined;
-
-            await global.BUNEXT_SSR_BUNDLER_CTX?.dispose();
-            global.BUNEXT_SSR_BUNDLER_CTX = undefined;
-        } catch (error) {}
 
         await allPagesESBuildContextBundler({
             post_build_fn: async (params) => {
                 await serverPostBuildFn(params);
             },
         });
+
+        // Production never rebuilds incrementally; don't keep esbuild's
+        // build state alive for the rest of the process.
+        if (!isDevelopment()) {
+            await disposeBundlerContexts();
+        }
     } catch (error: any) {
         logBuildErrorsOnce(
             [{ text: error?.message || String(error) }],

src/functions/server/handle-routes.ts

@@ -13,6 +13,7 @@ import path from "path";
 import grabDirNames from "../../utils/grab-dir-names";
 import grabRelativePath from "../../utils/grab-relative-path";
 import { RequestBodyTooLargeError } from "../../utils/read-request-body";
+import importFresh from "../../utils/import-fresh";
 
 const { ROOT_DIR } = grabDirNames();
 
@@ -50,7 +51,6 @@ export default async function ({ req }: Params): Promise<Response> {
         }
 
         let module: any;
-        const now = Date.now();
 
         const relative_match_path = grabRelativePath(match.filePath);
 
@@ -63,12 +63,9 @@ export default async function ({ req }: Params): Promise<Response> {
                 global.BUNEXT_SSR_BUNDLER_CTX_MAP[relative_match_path].path,
             );
 
-            module = await import(`${target_import}?t=${now}`);
+            module = await importFresh(target_import);
         } else {
-            const import_path = is_dev
+            module = await importFresh(match.filePath);
-                ? `${match.filePath}?t=${now}`
-                : match.filePath;
-            module = await import(import_path);
         }
 
         const config = module.config as BunextServerRouteConfig | undefined;

src/functions/server/start-server.ts

@@ -2,10 +2,7 @@ import _ from "lodash";
 import { log } from "../../utils/log";
 import serverParamsGen from "./server-params-gen";
 import isDevelopment from "../../utils/is-development";
-import {
+import { watcherWatchdogTick } from "./watcher-esbuild-ctx";
-    restartWatcher,
-    watcherRestartAvailable,
-} from "./watcher-esbuild-ctx";
 
 export default async function startServer() {
     const serverParams = await serverParamsGen();
@@ -18,15 +15,9 @@ export default async function startServer() {
     log.server(`http://${server.hostname}:${server.port}`);
 
     if (is_dev) {
-        // Watchdog: periodically re-create the FS watcher in case it went
+        // Watchdog: re-create the FS watcher if it went stale and stopped
-        // stale and stopped receiving events. Skipped while a recent restart
+        // receiving events.
-        // (e.g. by fullRebuild) is still fresh so the watcher isn't churned
+        setInterval(watcherWatchdogTick, 5000);
-        // twice in a row.
-        setInterval(() => {
-            if (watcherRestartAvailable()) {
-                restartWatcher();
-            }
-        }, 5000);
     }
 
     return server;

src/functions/server/watcher-esbuild-ctx.ts

@@ -1,6 +1,6 @@
 import chokidar from "chokidar";
 import path from "path";
-import { existsSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
 import grabDirNames from "../../utils/grab-dir-names";
 import fullRebuild from "./full-rebuild";
 import { AppData } from "../../data/app-data";
@@ -13,11 +13,21 @@ import serverPostBuildFn from "./server-post-build-fn";
 import { log } from "../../utils/log";
 import { logBuildErrorsOnce } from "../../utils/build-error-log";
 
-const { ROOT_DIR, BUNX_BUNDLER_ERROR_EXIT_FILE } = grabDirNames();
+const { ROOT_DIR, BUNX_CWD_DIR, BUNX_BUNDLER_ERROR_EXIT_FILE } =
+    grabDirNames();
 
-// Tracks the last watcher re-creation so the 5s watchdog in start-server
+// The watchdog writes this file and expects the watcher to report it. It
-// doesn't fight fullRebuild (which also restarts the watcher after a rebuild).
+// sits under `.bunext` (otherwise ignored), so only this path is watched.
+const WATCH_PROBE_DIR = path.join(BUNX_CWD_DIR, "watch-probe");
+const WATCH_PROBE_FILE = path.join(WATCH_PROBE_DIR, "probe");
+
+// Dedupes near-simultaneous restarts (fullRebuild, watchdog).
 let last_watcher_restart = 0;
+// The current watcher finished its initial scan; probes written before
+// that may not produce events.
+let watcher_ready = false;
+// A probe was written and the watcher hasn't reported it yet.
+let probe_pending = false;
 
 /**
  * Closes and re-creates the FS watcher. Deduped: callers that restart the
@@ -54,11 +64,30 @@ function grabPagesSnapshot(): string | undefined {
 }
 
 /**
- * True when the watcher was last (re)created long enough ago that the
+ * Called periodically by the dev server. Re-creates the watcher only when it
- * watchdog should consider re-creating it again.
+ * failed to report the probe written on the previous tick, i.e. when it went
+ * stale. A healthy watcher is left alone: re-creating it rescans the whole
+ * project tree.
  */
-export function watcherRestartAvailable() {
+export function watcherWatchdogTick() {
-    return Date.now() - last_watcher_restart > 6000;
+    if (!global.BUNEXT_PAGES_SRC_WATCHER || !watcher_ready) return;
+
+    if (probe_pending) {
+        restartWatcher();
+        return;
+    }
+
+    try {
+        mkdirSync(WATCH_PROBE_DIR, { recursive: true });
+        writeFileSync(WATCH_PROBE_FILE, String(Date.now()));
+        probe_pending = true;
+    } catch (error) {}
+}
+
+function isWatchProbePath(p: string) {
+    return (
+        p === WATCH_PROBE_FILE || p === WATCH_PROBE_DIR || p === BUNX_CWD_DIR
+    );
 }
 
 const TARGET_FILES_MATCH = /\.(tsx?|jsx?|css)$/;
@@ -191,10 +220,11 @@ function isPathExcluded(filename: string, full_file_path: string): boolean {
 // install watches (and deliver events) for trees the bundler never reads.
 function buildIgnoredPatterns() {
     const ignored: Array<RegExp | ((p: string) => boolean)> = [
-        /(^|[\/\\])\../,
+        (p: string) => !isWatchProbePath(p) && /(^|[\/\\])\../.test(p),
         /(^|[\/\\])node_modules([\/\\]|$)/,
         /(^|[\/\\])public([\/\\]|$)/,
-        /(^|[\/\\])\.bunext([\/\\]|$)/,
+        (p: string) =>
+            !isWatchProbePath(p) && /(^|[\/\\])\.bunext([\/\\]|$)/.test(p),
         /(^|[\/\\])\.git([\/\\]|$)/,
         /(^|[\/\\])dist([\/\\]|$)/,
         /bun\.lockb$/,
@@ -222,6 +252,13 @@ function buildIgnoredPatterns() {
 export default async function watcherEsbuildCTX(params?: {
     pages_snapshot?: string;
 }) {
+    try {
+        mkdirSync(WATCH_PROBE_DIR, { recursive: true });
+    } catch (error) {}
+
+    watcher_ready = false;
+    probe_pending = false;
+
     const pages_src_watcher = chokidar.watch(ROOT_DIR, {
         ignored: buildIgnoredPatterns(),
         persistent: true,
@@ -234,15 +271,19 @@ export default async function watcherEsbuildCTX(params?: {
     );
 
     const pages_snapshot = params?.pages_snapshot;
-    if (pages_snapshot !== undefined) {
     pages_src_watcher.on("ready", () => {
+        if (global.BUNEXT_PAGES_SRC_WATCHER === pages_src_watcher) {
+            watcher_ready = true;
+        }
+
+        if (pages_snapshot === undefined) return;
+
         const current = grabPagesSnapshot();
         if (current !== undefined && current !== pages_snapshot) {
             pending_structural = true;
             scheduleRebuild();
         }
     });
-    }
 
     global.BUNEXT_PAGES_SRC_WATCHER = pages_src_watcher as any;
 }
@@ -251,6 +292,13 @@ function handleEvent(
     event: "add" | "change" | "unlink" | "addDir" | "unlinkDir",
     filePath: string,
 ) {
+    if (isWatchProbePath(filePath)) {
+        if (filePath === WATCH_PROBE_FILE) {
+            probe_pending = false;
+        }
+        return;
+    }
+
     try {
         const filename = path.relative(ROOT_DIR, filePath);
         const full_file_path = filePath;

src/functions/server/web-pages/generate-web-html.tsx

@@ -180,8 +180,27 @@ export default async function genWebHTML({
     let render_error: any;
     let has_render_error = false;
 
+    const render_timeout_ms =
+        global.BUNEXT_CONFIG.ssr_render_timeout_ms ||
+        AppData["DefaultSSRRenderTimeoutMs"];
+
+    // Without a deadline, a Suspense boundary that never settles keeps the
+    // request (and its whole render tree) alive forever. The timer is
+    // cleared once the render ends so finished requests don't linger.
+    const render_abort = new AbortController();
+    const render_timeout = setTimeout(
+        () =>
+            render_abort.abort(
+                new RenderTimeoutError(
+                    `Page render timed out after ${render_timeout_ms}ms`,
+                ),
+            ),
+        render_timeout_ms,
+    );
+
     try {
         const stream = await renderToReadableStream(final_component, {
+            signal: render_abort.signal,
             onError(error: any) {
                 if (error?.message?.includes('unique "key" prop')) return;
 
@@ -190,12 +209,16 @@ export default async function genWebHTML({
                     render_error = error;
                 }
 
+                // A timeout has no useful stack; it's logged upstream.
+                if (!(error instanceof RenderTimeoutError)) {
                     original_console.error(error);
+                }
             },
         });
 
         htmlBody = await new Response(stream).text();
     } finally {
+        clearTimeout(render_timeout);
         restoreConsole();
     }
 
@@ -211,6 +234,8 @@ export default async function genWebHTML({
     return html;
 }
 
+class RenderTimeoutError extends Error {}
+
 let original_console: Pick<
     Console,
     "log" | "warn" | "error" | "info" | "debug"

src/functions/server/web-pages/grab-file-path-module.tsx

@@ -1,45 +0,0 @@
-import isDevelopment from "../../../utils/is-development";
-import * as esbuild from "esbuild";
-import grabDirNames from "../../../utils/grab-dir-names";
-import path from "path";
-import tailwindEsbuildPlugin from "./tailwind-esbuild-plugin";
-
-type Params = {
-    file_path: string;
-    out_file?: string;
-};
-
-export default async function grabFilePathModule<T extends any = any>({
-    file_path,
-    out_file,
-}: Params): Promise<T> {
-    const dev = isDevelopment();
-    const { BUNX_CWD_MODULE_CACHE_DIR } = grabDirNames();
-    const target_cache_file_path =
-        out_file ||
-        path.join(BUNX_CWD_MODULE_CACHE_DIR, `${path.basename(file_path)}.js`);
-
-    await esbuild.build({
-        entryPoints: [file_path],
-        bundle: true,
-        format: "esm",
-        target: "es2020",
-        platform: "node",
-        // external: ["react", "react-dom"],
-        minify: true,
-        define: {
-            "process.env.NODE_ENV": JSON.stringify(
-                dev ? "development" : "production",
-            ),
-        },
-        metafile: true,
-        plugins: [tailwindEsbuildPlugin],
-        jsx: "automatic",
-        outfile: target_cache_file_path,
-    });
-
-    // Loader.registry.delete(target_cache_file_path);
-    const module = await import(`${target_cache_file_path}?t=${Date.now()}`);
-
-    return module as T;
-}

src/types/index.ts

@@ -126,6 +126,11 @@ export type BunextConfig = {
      * `/robots.txt` disallows all crawlers regardless of `public/robots.txt`.
      */
     disable_seo?: boolean;
+    /**
+     * Maximum time (ms) a page's server render may take before it is
+     * aborted and answered with a 500. Defaults to 30000.
+     */
+    ssr_render_timeout_ms?: number;
 };
 
 export type BunextConfigMiddlewareParams = {

src/utils/import-fresh.ts

@@ -1,13 +1,75 @@
+import { existsSync, statSync } from "fs";
+import path from "path";
 import isDevelopment from "./is-development";
 
 /**
- * Dev: bypass Bun's module registry so rebuilt files are picked up.
+ * File path -> mtime of the version currently held in Bun's module
- * Prod: import by stable path so each module is loaded (and kept) once.
+ * registry (dev only).
- * A unique `?t=` per call creates a new, never-evicted module record, so
- * using it in production leaks memory on every request.
  */
-export default function importFresh<T = any>(file_path: string): Promise<T> {
+const loaded_versions = new Map<string, number | undefined>();
-    return import(
+
-        isDevelopment() ? `${file_path}?t=${Date.now()}` : file_path
+/**
-    );
+ * Imports a module by its stable path.
+ *
+ * Dev: when the file changed since it was last imported, its registry
+ * entry is evicted first so the new version is evaluated and the old one
+ * can be garbage collected. A cache-busting `?t=` query would instead
+ * create a new, never-evicted module record on every call.
+ *
+ * Prod: plain import, so each module is loaded (and kept) once.
+ */
+export default async function importFresh<T = any>(
+    file_path: string,
+): Promise<T> {
+    if (!isDevelopment()) {
+        return import(file_path);
+    }
+
+    let mtime: number | undefined;
+    try {
+        mtime = statSync(file_path).mtimeMs;
+    } catch {}
+
+    if (
+        loaded_versions.has(file_path) &&
+        loaded_versions.get(file_path) !== mtime
+    ) {
+        evictModule(file_path);
+    }
+
+    try {
+        const mod = await import(file_path);
+        loaded_versions.set(file_path, mtime);
+        return mod;
+    } catch (error) {
+        // Don't keep a failed evaluation around: the next request retries.
+        evictModule(file_path);
+        throw error;
+    }
+}
+
+/**
+ * Drops a module from Bun's registry so its memory can be reclaimed and the
+ * next import re-evaluates it. Only the module itself is evicted, not the
+ * modules it imports.
+ */
+export function evictModule(file_path: string) {
+    delete require.cache[file_path];
+    loaded_versions.delete(file_path);
+}
+
+/**
+ * Evicts every registry entry under `dir` whose file no longer exists. Bundle
+ * outputs (entries and shared chunks) are content-hashed and esbuild deletes
+ * the superseded ones on rebuild, so a missing file means no current module
+ * imports it anymore.
+ */
+export function evictDeletedModules(dir: string) {
+    const prefix = dir.endsWith(path.sep) ? dir : dir + path.sep;
+
+    for (const key of Object.keys(require.cache)) {
+        if (key.startsWith(prefix) && !existsSync(key)) {
+            evictModule(key);
+        }
+    }
 }