feat(dev): detect 'use cache' module-scope deadlocks early in dev (#1126)

packages/vinext/src/config/next-config.ts

@@ -405,6 +405,8 @@ export type ResolvedNextConfig = {
    * and partial object config into concrete thresholds.
    */
   prefetchInlining: PrefetchInliningConfig;
+  /** Dev "use cache" fill timeout in seconds. Defaults to 54. */
+  useCacheTimeout: number;
   redirects: NextRedirect[];
   rewrites: {
     beforeFiles: NextRewrite[];
@@ -1540,6 +1542,7 @@ export async function resolveNextConfig(
       appNavFailHandling: false,
       gestureTransition: false,
       prefetchInlining: false,
+      useCacheTimeout: 54,
       redirects: [],
       rewrites: { beforeFiles: [], afterFiles: [], fallback: [] },
       headers: [],
@@ -1874,6 +1877,10 @@ export async function resolveNextConfig(
     appNavFailHandling: experimental?.appNavFailHandling === true,
     gestureTransition: experimental?.gestureTransition === true,
     prefetchInlining,
+    useCacheTimeout:
+      typeof experimental?.useCacheTimeout === "number" && experimental.useCacheTimeout > 0
+        ? experimental.useCacheTimeout
+        : 54,
     redirects,
     rewrites,
     headers,

packages/vinext/src/index.ts

@@ -344,6 +344,19 @@ function hasServerOnlyMarkerImport(code: string): boolean {
 }
 
 const __dirname = import.meta.dirname;
+
+// Lazy load the use-cache probe pool so it is only loaded when the dev
+// server starts (configureServer), not during production builds.
+let _probePoolModulePromise: Promise<typeof import("./server/use-cache-probe-pool.js")> | null =
+  null;
+function getProbePoolModule(): Promise<typeof import("./server/use-cache-probe-pool.js")> {
+  _probePoolModulePromise ??= import("./server/use-cache-probe-pool.js").catch((error) => {
+    _probePoolModulePromise = null;
+    throw error;
+  });
+  return _probePoolModulePromise;
+}
+
 type VitePluginReactModule = typeof import("@vitejs/plugin-react");
 
 function resolveOptionalDependency(projectRoot: string, specifier: string): string | null {
@@ -2133,6 +2146,9 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
         defines["process.env.__VINEXT_DEPLOYMENT_ID"] = JSON.stringify(
           nextConfig.deploymentId ?? "",
         );
+        defines["process.env.__VINEXT_USE_CACHE_TIMEOUT_MS"] = JSON.stringify(
+          nextConfig.useCacheTimeout * 1_000,
+        );
         // Public `process.env.NEXT_DEPLOYMENT_ID` — Next.js statically inlines
         // this into client (and web worker) bundles via its DefinePlugin so
         // that user code like `new Worker(new URL('./w.ts', import.meta.url))`
@@ -4099,7 +4115,7 @@ export const loadServerActionClient = ${
         },
       },
 
-      configureServer(server: ViteDevServer) {
+      async configureServer(server: ViteDevServer) {
         // Watch route files for additions/removals to invalidate route cache.
         const pageExtensions = fileMatcher.extensionRegex;
 
@@ -4194,11 +4210,30 @@ export const loadServerActionClient = ${
           pagesRunner?.clearCache();
         }
 
-        function invalidateAppRoutingModules() {
+        async function invalidateAppRoutingModules() {
           invalidateAppRouteCache();
           invalidateMetadataFileCache();
           invalidateRscEntryModule();
           invalidateRootParamsModule();
+          await resetUseCacheProbePool();
+        }
+
+        async function resetUseCacheProbePool() {
+          const { tearDownUseCacheProbePool, initUseCacheProbePool } = await getProbePoolModule();
+          // Tear down the use-cache probe pool so the next probe starts with
+          // fresh code after HMR invalidation.
+          tearDownUseCacheProbePool();
+          // Re-initialize so probes continue working after HMR.
+          const rscEnv = server.environments["rsc"];
+          if (rscEnv) {
+            initUseCacheProbePool(rscEnv);
+          }
+        }
+
+        function tearDownUseCacheProbePoolOnServerClose() {
+          void getProbePoolModule().then(({ tearDownUseCacheProbePool }) => {
+            tearDownUseCacheProbePool();
+          });
         }
 
         let hybridRouteValidation: Promise<void> = Promise.resolve();
@@ -4341,7 +4376,7 @@ export const loadServerActionClient = ${
             routeChanged = true;
           }
           if (hasAppDir && shouldInvalidateAppRouteFile(appDir, filePath, fileMatcher)) {
-            invalidateAppRoutingModules();
+            void invalidateAppRoutingModules();
             regenerateAppRouteTypes();
             routeChanged = true;
           }
@@ -4382,7 +4417,7 @@ export const loadServerActionClient = ${
             routeChanged = true;
           }
           if (hasAppDir && shouldInvalidateAppRouteFile(appDir, filePath, fileMatcher)) {
-            invalidateAppRoutingModules();
+            void invalidateAppRoutingModules();
             regenerateAppRouteTypes();
             routeChanged = true;
           }
@@ -4393,6 +4428,17 @@ export const loadServerActionClient = ${
             revalidateHybridRoutes();
           }
         });
+        server.watcher.on("change", (filePath: string) => {
+          if (
+            hasAppDir &&
+            isInsideDirectory(appDir, filePath) &&
+            fileMatcher.extensionRegex.test(filePath)
+          ) {
+            void resetUseCacheProbePool();
+          }
+        });
+        server.watcher.once("close", tearDownUseCacheProbePoolOnServerClose);
+        server.httpServer?.once("close", tearDownUseCacheProbePoolOnServerClose);
 
         // ── Dev request origin check ─────────────────────────────────────
         // Registered directly (not in the returned function) so it runs
@@ -4527,6 +4573,18 @@ export const loadServerActionClient = ${
           //      it is flushed to the client.
           //   2. Logs the full request after res finishes, using those timings.
           if (hasAppDir) {
+            // Initialize the "use cache" deadlock probe pool for the App
+            // Router dev server. We bind to the RSC environment because
+            // "use cache" functions run inside the RSC module graph.
+            const rscEnv = server.environments["rsc"];
+            if (rscEnv) {
+              getProbePoolModule()
+                .then(({ initUseCacheProbePool }) => initUseCacheProbePool(rscEnv))
+                .catch((err) => {
+                  console.warn("[vinext] Failed to initialize use-cache probe pool:", err);
+                });
+            }
+
             server.middlewares.use((req, res, next) => {
               const url = req.url ?? "/";
               // Skip Vite internals, HMR, and static assets.

packages/vinext/src/server/dev-module-runner.ts

@@ -65,7 +65,7 @@ import type { DevEnvironment } from "vite";
  * environment types — including Cloudflare's custom environments that don't
  * support the hot-channel-based transport.
  */
-type DevEnvironmentLike = {
+export type DevEnvironmentLike = {
   fetchModule: (
     id: string,
     importer?: string,