@reckona/mreact-router 0.0.182 → 0.0.183

package/src/build.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { Dirent } from "node:fs";
 import {
   copyFile,
@@ -108,7 +109,8 @@ const nativeEscapeTransform = {
   batchImportSource: "@reckona/mreact-router/native-escape",
 } as const;
 
-const defaultBuildConcurrency = Math.max(1, Math.min(2, availableParallelism()));
+const maxDefaultBuildConcurrency = 8;
+const buildConcurrencyStorage = new AsyncLocalStorage<number>();
 const serverArtifactFilesystemConcurrency = 2;
 
 type ServerTransformOutput = ReturnType<typeof transform>;
@@ -219,6 +221,29 @@ export interface BuildAppResult {
   routes: AppRoute[];
 }
 
+interface IncrementalBuildCacheManifest {
+  fingerprint: string;
+  version: 1;
+}
+
+interface IncrementalBuildServerManifestOutputs {
+  serverModuleFiles?: Record<string, string>;
+  serverModuleRenderFiles?: Record<string, string>;
+  serverModuleRequestFiles?: Record<string, string>;
+}
+
+interface IncrementalBuildClientManifestOutputs {
+  assets?: readonly string[];
+  publicAssets?: readonly string[];
+  routes: readonly {
+    css?: readonly string[];
+    imports?: readonly string[];
+    navigationScript?: string | undefined;
+    script?: string | undefined;
+    sourceMap?: string | undefined;
+  }[];
+}
+
 /**
  * Describes the generated import policy artifact consumed by built request handlers.
  */
@@ -377,10 +402,24 @@ type StaticParams = Record<string, string | number | boolean | readonly string[]
  * Use this from custom build scripts when the CLI is too coarse-grained; the returned manifest paths describe the files written under `outDir`. The build reads route files, loaders, middleware, metadata, server actions, and client references, so callers should pass the same project root and source allow-list they expect to deploy.
  */
 export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult> {
+  const project = resolveAppRouterProjectOptions(options);
+  const buildConcurrency = resolveBuildConcurrency(
+    options.buildConcurrency ?? project.buildConcurrency,
+  );
+
+  return await buildConcurrencyStorage.run(
+    buildConcurrency,
+    async () => await buildAppWithResolvedProject(options, project),
+  );
+}
+
+async function buildAppWithResolvedProject(
+  options: BuildAppOptions,
+  project: ResolvedAppRouterProject,
+): Promise<BuildAppResult> {
   const timingSink = options.onBuildPhaseTiming;
   const progressSink = options.onBuildProgress;
   const shouldTrackBuildPhases = timingSink !== undefined || progressSink !== undefined;
-  const project = resolveAppRouterProjectOptions(options);
   const buildTargets = resolveBuildTargets(options.targets ?? project.buildTargets);
   const shouldBuildCloudflare = buildTargets.includes("cloudflare");
   const shouldBuildAwsLambda = buildTargets.includes("aws-lambda");
@@ -405,6 +444,14 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
   const serverDir = join(options.outDir, "server");
   const clientDir = join(options.outDir, "client");
   const cloudflareDir = join(options.outDir, "cloudflare");
+  const incrementalBuildFingerprint = await createIncrementalBuildCacheFingerprint({
+    buildTargets,
+    files,
+    project,
+    routes,
+    viteDefine,
+    vitePlugins,
+  });
   const sourceAnalysis =
     shouldTrackBuildPhases === false
       ? await analyzeBuildRouteSources({
@@ -452,6 +499,17 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
     );
   }
 
+  if (
+    incrementalBuildFingerprint !== undefined &&
+    (await isIncrementalBuildCacheHit({
+      buildTargets,
+      fingerprint: incrementalBuildFingerprint,
+      outDir: options.outDir,
+    }))
+  ) {
+    return { routes };
+  }
+
   if (shouldTrackBuildPhases === false) {
     await rm(options.outDir, { force: true, recursive: true });
     await Promise.all([
@@ -783,9 +841,284 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
     });
   }
 
+  if (incrementalBuildFingerprint !== undefined) {
+    await writeIncrementalBuildCacheManifest(options.outDir, incrementalBuildFingerprint);
+  }
+
   return { routes };
 }
 
+const incrementalBuildCacheFilename = "build-cache.json";
+const incrementalBuildCacheVersion = 1;
+
+async function createIncrementalBuildCacheFingerprint(options: {
+  buildTargets: readonly AppRouterBuildTarget[];
+  files: Record<string, string>;
+  project: ResolvedAppRouterProject;
+  routes: readonly AppRoute[];
+  viteDefine: UserConfig["define"] | undefined;
+  vitePlugins: readonly PluginOption[] | undefined;
+}): Promise<string | undefined> {
+  if (options.vitePlugins !== undefined && options.vitePlugins.length > 0) {
+    return undefined;
+  }
+
+  let define: string;
+  try {
+    const serializedDefine = JSON.stringify(options.viteDefine ?? null);
+    if (serializedDefine === undefined) {
+      return undefined;
+    }
+    define = serializedDefine;
+  } catch {
+    return undefined;
+  }
+
+  const [publicAssets, appConventionAssets] = await Promise.all([
+    collectBuildInputFileHashes(options.project.publicDir, options.project.projectRoot),
+    collectAppConventionAssetInputHashes(options.project.routesDir, options.project.projectRoot),
+  ]);
+  const sourceFiles = Object.keys(options.files)
+    .sort()
+    .map((file) => [normalizeBuildInputPath(file), hashText(options.files[file] ?? "")] as const);
+  const routes = options.routes
+    .map((route) => ({
+      file: normalizeBuildInputPath(relative(options.project.projectRoot, route.file)),
+      kind: route.kind,
+      path: route.path,
+    }))
+    .sort((left, right) => left.file.localeCompare(right.file));
+  const payload = {
+    appDir: normalizeBuildInputPath(relative(options.project.projectRoot, options.project.routesDir)),
+    assetBaseUrl: options.project.assetBaseUrl ?? null,
+    clientConsolePureFunctions: options.project.clientConsolePureFunctions ?? [],
+    clientSourceMaps: options.project.clientSourceMaps,
+    define,
+    nodeEnv: process.env.NODE_ENV ?? null,
+    publicAssetBaseUrl: options.project.publicAssetBaseUrl ?? null,
+    publicDir: normalizeBuildInputPath(relative(options.project.projectRoot, options.project.publicDir)),
+    routes,
+    sourceDirs: options.project.allowedSourceDirs
+      .map((directory) => normalizeBuildInputPath(relative(options.project.projectRoot, directory)))
+      .sort(),
+    sourceFiles,
+    targets: [...options.buildTargets].sort(),
+    version: incrementalBuildCacheVersion,
+    publicAssets,
+    appConventionAssets,
+  };
+
+  return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+async function isIncrementalBuildCacheHit(options: {
+  buildTargets: readonly AppRouterBuildTarget[];
+  fingerprint: string;
+  outDir: string;
+}): Promise<boolean> {
+  const cache = await readJsonBuildOutput<IncrementalBuildCacheManifest>(
+    join(options.outDir, incrementalBuildCacheFilename),
+  );
+  if (cache === undefined) {
+    return false;
+  }
+
+  return (
+    cache.version === incrementalBuildCacheVersion &&
+    cache.fingerprint === options.fingerprint &&
+    (await hasRequiredIncrementalBuildOutputs(options.outDir, options.buildTargets))
+  );
+}
+
+async function hasRequiredIncrementalBuildOutputs(
+  outDir: string,
+  buildTargets: readonly AppRouterBuildTarget[],
+): Promise<boolean> {
+  const serverManifestFile = join(outDir, "server", "manifest.json");
+  const clientManifestFile = join(outDir, "client", "manifest.json");
+  const requiredFiles = [
+    serverManifestFile,
+    join(outDir, "server", "import-policy.json"),
+    clientManifestFile,
+    join(outDir, "client", ".vite", "manifest.json"),
+    join(outDir, "routes.d.ts"),
+    join(outDir, "public-assets.d.ts"),
+    ...(buildTargets.includes("aws-lambda")
+      ? [join(outDir, "aws-lambda", "mreact-handler.mjs")]
+      : []),
+    ...(buildTargets.includes("cloudflare") ? [join(outDir, "cloudflare", "worker.mjs")] : []),
+  ];
+  const [serverManifest, clientManifest] = await Promise.all([
+    readJsonBuildOutput<IncrementalBuildServerManifestOutputs>(serverManifestFile),
+    readJsonBuildOutput<IncrementalBuildClientManifestOutputs>(clientManifestFile),
+  ]);
+  if (serverManifest === undefined || clientManifest === undefined) {
+    return false;
+  }
+
+  for (const file of [
+    ...Object.values(serverManifest.serverModuleFiles ?? {}),
+    ...Object.values(serverManifest.serverModuleRenderFiles ?? {}),
+    ...Object.values(serverManifest.serverModuleRequestFiles ?? {}),
+  ]) {
+    requiredFiles.push(join(outDir, "server", file));
+  }
+
+  for (const file of collectClientManifestOutputFiles(clientManifest)) {
+    requiredFiles.push(join(outDir, "client", file));
+  }
+
+  for (const file of requiredFiles) {
+    if (!(await isExistingFile(file))) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function collectClientManifestOutputFiles(
+  manifest: IncrementalBuildClientManifestOutputs,
+): string[] {
+  const files = new Set<string>();
+
+  for (const asset of manifest.assets ?? []) {
+    files.add(asset);
+  }
+  for (const asset of manifest.publicAssets ?? []) {
+    files.add(asset);
+    files.add(`public/${asset}`);
+  }
+  for (const route of manifest.routes) {
+    for (const file of [
+      route.script,
+      route.sourceMap,
+      route.navigationScript,
+      ...(route.css ?? []),
+      ...(route.imports ?? []),
+    ]) {
+      if (file !== undefined) {
+        files.add(file);
+      }
+    }
+  }
+
+  return [...files];
+}
+
+async function readJsonBuildOutput<T>(file: string): Promise<T | undefined> {
+  try {
+    return JSON.parse(await readFile(file, "utf8")) as T;
+  } catch (error) {
+    if (
+      (isNodeError(error) && error.code === "ENOENT") ||
+      error instanceof SyntaxError
+    ) {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+async function writeIncrementalBuildCacheManifest(
+  outDir: string,
+  fingerprint: string,
+): Promise<void> {
+  const cache = {
+    fingerprint,
+    version: incrementalBuildCacheVersion,
+  } satisfies IncrementalBuildCacheManifest;
+
+  await writeFile(
+    join(outDir, incrementalBuildCacheFilename),
+    `${JSON.stringify(cache, null, 2)}\n`,
+  );
+}
+
+async function collectBuildInputFileHashes(
+  directory: string,
+  projectRoot: string,
+): Promise<readonly (readonly [string, string])[]> {
+  if (!(await isPublicAssetDirectory(directory))) {
+    return [];
+  }
+
+  const files = await collectFiles(directory);
+  const hashes = await mapWithBuildConcurrency(
+    files,
+    async (file) =>
+      [
+        normalizeBuildInputPath(relative(projectRoot, file)),
+        hashBuffer(await readFile(file)),
+      ] as const,
+  );
+
+  return hashes.sort(([left], [right]) => left.localeCompare(right));
+}
+
+async function collectAppConventionAssetInputHashes(
+  appDir: string,
+  projectRoot: string,
+): Promise<readonly (readonly [string, string])[]> {
+  const entries = await readdir(appDir, { withFileTypes: true });
+  const assetFiles = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => join(appDir, entry.name))
+    .filter((file) => isAppFileConventionAsset(file, appDir));
+  const hashes = await mapWithBuildConcurrency(
+    assetFiles,
+    async (file) =>
+      [
+        normalizeBuildInputPath(relative(projectRoot, file)),
+        hashBuffer(await readFile(file)),
+      ] as const,
+  );
+
+  return hashes.sort(([left], [right]) => left.localeCompare(right));
+}
+
+async function isExistingFile(file: string): Promise<boolean> {
+  try {
+    return (await stat(file)).isFile();
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+function normalizeBuildInputPath(path: string): string {
+  return path.split(sep).join("/");
+}
+
+function hashBuffer(buffer: Buffer): string {
+  return createHash("sha256").update(buffer).digest("hex").slice(0, 16);
+}
+
+function defaultBuildConcurrency(): number {
+  return Math.max(1, Math.min(maxDefaultBuildConcurrency, availableParallelism()));
+}
+
+function currentBuildConcurrency(): number {
+  return buildConcurrencyStorage.getStore() ?? defaultBuildConcurrency();
+}
+
+function resolveBuildConcurrency(
+  value: number | undefined,
+  cores = availableParallelism(),
+): number {
+  const resolved = value ?? Math.max(1, Math.min(maxDefaultBuildConcurrency, cores));
+
+  if (!Number.isSafeInteger(resolved) || resolved < 1) {
+    throw new Error("mreactRouter buildConcurrency must be a positive integer.");
+  }
+
+  return resolved;
+}
+
 function typedRoutesDeclaration(routes: readonly AppRoute[]): string {
   const routePaths = Array.from(
     new Set(
@@ -803,21 +1136,60 @@ function typedRoutesDeclaration(routes: readonly AppRoute[]): string {
     return left.localeCompare(right);
   });
   const routeUnion = routePaths.map((routePath) => JSON.stringify(routePath)).join(" | ");
+  const routeParamEntries = routePaths.map(
+    (routePath) => `  readonly ${JSON.stringify(routePath)}: ${routeParamsType(routePath)};`,
+  );
   return [
-    `import type { AppRouteLinkHref as MreactAppRouteLinkHref } from "@reckona/mreact-router";`,
+    `import type { AppRouteLinkHref as MreactAppRouteLinkHref, RouteParamsFor as MreactRouteParamsFor } from "@reckona/mreact-router";`,
     ``,
     `export type AppRoutePath = ${routeUnion === "" ? "never" : routeUnion};`,
     `export type AppRouteHref = MreactAppRouteLinkHref<AppRoutePath>;`,
+    `export type AppRouteParams<Path extends AppRoutePath> = MreactRouteParamsFor<Path>;`,
+    `export interface AppRouteParamMap {`,
+    ...(routeParamEntries.length === 0 ? [`  readonly [path: string]: never;`] : routeParamEntries),
+    `}`,
     ``,
     `declare module "@reckona/mreact-router/link" {`,
     `  interface AppRouteDeclarations {`,
     `    readonly path: AppRoutePath;`,
+    `    readonly params: AppRouteParamMap;`,
     `  }`,
     `}`,
     ``,
   ].join("\n");
 }
 
+function routeParamsType(routePath: string): string {
+  const params = routePath
+    .split("/")
+    .flatMap((segment): Array<{ catchAll: boolean; name: string }> => {
+      if (segment.startsWith(":...")) {
+        return [{ catchAll: true, name: segment.slice(4) }];
+      }
+
+      if (segment.startsWith(":")) {
+        return [{ catchAll: false, name: segment.slice(1) }];
+      }
+
+      return [];
+    });
+
+  if (params.length === 0) {
+    return "Record<never, never>";
+  }
+
+  return `{ ${params
+    .map(
+      (param) =>
+        `readonly ${propertyKeyForType(param.name)}: ${param.catchAll ? "readonly string[]" : "string"}`,
+    )
+    .join("; ")} }`;
+}
+
+function propertyKeyForType(value: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(value) ? value : JSON.stringify(value);
+}
+
 function typedPublicAssetsDeclaration(publicAssets: readonly string[]): string {
   const assetUnion = publicAssets.map((assetPath) => JSON.stringify(assetPath)).join(" | ");
 
@@ -861,7 +1233,7 @@ function roundBuildPhaseMs(value: number): number {
 async function mapWithBuildConcurrency<T, R>(
   items: readonly T[],
   map: (item: T, index: number) => Promise<R>,
-  concurrency = defaultBuildConcurrency,
+  concurrency = currentBuildConcurrency(),
 ): Promise<R[]> {
   if (items.length === 0) {
     return [];
@@ -897,6 +1269,27 @@ export async function __mapWithBuildConcurrencyForTests<T, R>(
   return await mapWithBuildConcurrency(items, map, concurrency);
 }
 
+async function mapServerOutputsWithBuildConcurrency<R>(
+  serverOutputs: readonly ServerOutputMode[],
+  map: (serverOutput: ServerOutputMode, index: number) => Promise<R>,
+): Promise<R[]> {
+  return await mapWithBuildConcurrency(serverOutputs, map, 1);
+}
+
+export async function __mapServerOutputsWithBuildConcurrencyForTests<R>(
+  serverOutputs: readonly ServerOutputMode[],
+  map: (serverOutput: ServerOutputMode, index: number) => Promise<R>,
+): Promise<R[]> {
+  return await mapServerOutputsWithBuildConcurrency(serverOutputs, map);
+}
+
+export function __resolveBuildConcurrencyForTests(
+  value: number | undefined,
+  cores: number,
+): number {
+  return resolveBuildConcurrency(value, cores);
+}
+
 async function analyzeBuildRouteSources(options: {
   clientRouteInferenceCache: ClientRouteInferenceCache;
   files: Record<string, string>;
@@ -2479,7 +2872,7 @@ async function buildServerModuleArtifacts(options: {
         });
       }
 
-      const serverOutputArtifacts = await mapWithBuildConcurrency(
+      const serverOutputArtifacts = await mapServerOutputsWithBuildConcurrency(
         serverOutputs,
         async (serverOutput) => {
           const output = await transformServerRouteSource({

package/src/config.ts

@@ -26,6 +26,7 @@ export interface AppRouterProductionOptions {
 
 export interface AppRouterProjectOptions {
   assetBaseUrl?: string | undefined;
+  buildConcurrency?: number | undefined;
   buildTargets?: readonly AppRouterBuildTarget[] | undefined;
   clientSourceMaps?: AppRouterClientSourceMapOption | undefined;
   /**
@@ -48,6 +49,7 @@ export interface AppRouterProjectOptions {
 export interface ResolvedAppRouterProject {
   allowedSourceDirs: readonly string[];
   assetBaseUrl?: string | undefined;
+  buildConcurrency?: number | undefined;
   buildTargets: readonly AppRouterBuildTarget[];
   clientSourceMaps: AppRouterClientSourceMapMode;
   clientConsolePureFunctions?: readonly string[] | undefined;
@@ -76,6 +78,9 @@ export function resolveAppRouterProjectOptions(
         resolveProjectPath(appDir, directory, "allowedSourceDirs"),
       ),
       ...(options.assetBaseUrl === undefined ? {} : { assetBaseUrl: options.assetBaseUrl }),
+      ...(options.buildConcurrency === undefined
+        ? {}
+        : { buildConcurrency: options.buildConcurrency }),
       buildTargets: resolveBuildTargets(options.buildTargets),
       clientSourceMaps: resolveClientSourceMapMode(options.clientSourceMaps),
       ...(clientConsolePureFunctions === undefined ? {} : { clientConsolePureFunctions }),
@@ -98,6 +103,9 @@ export function resolveAppRouterProjectOptions(
       resolveProjectPath(projectRoot, directory, "allowedSourceDirs"),
     ),
     ...(options.assetBaseUrl === undefined ? {} : { assetBaseUrl: options.assetBaseUrl }),
+    ...(options.buildConcurrency === undefined
+      ? {}
+      : { buildConcurrency: options.buildConcurrency }),
     buildTargets: resolveBuildTargets(options.buildTargets),
     clientSourceMaps: resolveClientSourceMapMode(options.clientSourceMaps),
     ...(clientConsolePureFunctions === undefined ? {} : { clientConsolePureFunctions }),

package/src/render.ts

@@ -195,6 +195,7 @@ export interface RenderAppRequestOptions {
   instrumentation?: RouterInstrumentation | undefined;
   logger?: AppRouterLogger | undefined;
   navigationScripts?: ReadonlyMap<string, string> | undefined;
+  onRenderError?: ((error: unknown) => void) | undefined;
   onResponse?: AppRouterResponseHook | undefined;
   queryClient?: QueryClient | undefined;
   request: Request;
@@ -794,6 +795,7 @@ export type AppRouterMiddlewareResult =
 export async function resolveAppRouterMiddleware(options: {
   appDir: string;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   importPolicy?: AppRouterImportPolicy | undefined;
   instrumentation?: RouterInstrumentation | undefined;
   middlewareControl?: RouteMiddlewareControl | undefined;
@@ -862,6 +864,7 @@ async function renderAppRequestInternal(
       ? ({ request: options.request, type: "continue" } satisfies AppRouterMiddlewareResult)
       : await resolveAppRouterMiddleware({
           appDir: options.appDir,
+          devServerModuleCacheVersion: options.devServerModuleCacheVersion,
           importPolicy: options.importPolicy,
           instrumentation: options.instrumentation,
           middlewareControl,
@@ -1097,6 +1100,7 @@ async function renderAppRequestInternal(
           filename: matched.route.file,
           importPolicy: options.importPolicy,
           instrumentation: options.instrumentation,
+          devServerModuleCacheVersion: options.devServerModuleCacheVersion,
           request: options.request,
           routeId: routeIdForPath(matched.route.path),
           routePath: matched.route.path,
@@ -1629,6 +1633,7 @@ async function renderAppRequestInternal(
       filename: "error.mreact.tsx",
       pageFile: matched.route.file,
     });
+    options.onRenderError?.(error);
 
     const response = await renderSpecialRoute({
       appDir: options.appDir,
@@ -2370,6 +2375,7 @@ function devExternalSourceDirs(
 async function runMiddleware(options: {
   appDir: string;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   importPolicy?: AppRouterImportPolicy | undefined;
   instrumentation?: RouterInstrumentation | undefined;
   middlewareControl?: RouteMiddlewareControl | undefined;
@@ -2440,6 +2446,7 @@ async function runMiddleware(options: {
         serverModules: options.serverModules,
         serverModuleCacheVersion: options.serverModuleCacheVersion,
         serverSourceFiles: options.serverSourceFiles,
+        devServerModuleCacheVersion: options.devServerModuleCacheVersion,
         vitePlugins: options.vitePlugins,
       });
     } finally {
@@ -2538,6 +2545,7 @@ async function loadMiddlewareModule(options: {
   appDir: string;
   code?: string | undefined;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   file: string;
   importPolicy?: AppRouterImportPolicy | undefined;
   serverModules?: ReadonlyMap<string, BuiltServerModuleArtifact> | undefined;
@@ -2552,10 +2560,12 @@ async function loadMiddlewareModule(options: {
       options.serverModuleCacheVersion,
       options.serverSourceFiles,
     ));
+  const moduleCacheVersion =
+    options.serverModuleCacheVersion ?? options.devServerModuleCacheVersion;
   const cacheKey =
-    options.serverModuleCacheVersion === undefined
+    moduleCacheVersion === undefined
       ? undefined
-      : `middleware\0${options.appDir}\0${options.file}\0${options.serverModuleCacheVersion}\0${memoizedHashText(code)}\0${importPolicyCacheKey(options.importPolicy)}\0${viteDefineCacheKey(options.define)}\0${vitePluginsCacheKey(options.vitePlugins)}`;
+      : `middleware\0${options.serverModuleCacheVersion === undefined ? "dev" : "build"}\0${options.appDir}\0${options.file}\0${moduleCacheVersion}\0${memoizedHashText(code)}\0${importPolicyCacheKey(options.importPolicy)}\0${viteDefineCacheKey(options.define)}\0${vitePluginsCacheKey(options.vitePlugins)}`;
 
   if (cacheKey !== undefined) {
     const cached = readRouterRuntimeCacheEntry(
@@ -2576,6 +2586,7 @@ async function loadMiddlewareModule(options: {
     file: options.file,
     importPolicy: options.importPolicy,
     prebuiltArtifact: prebuiltRequestModuleArtifact(options.serverModules, options.file, code),
+    devServerModuleCacheVersion: options.devServerModuleCacheVersion,
     serverModuleCacheVersion: options.serverModuleCacheVersion,
     vitePlugins: options.vitePlugins,
   }).catch((error) => {
@@ -2637,6 +2648,7 @@ async function loadBundledMiddlewareModule(options: {
   appDir: string;
   code: string;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   file: string;
   importPolicy?: AppRouterImportPolicy | undefined;
   prebuiltArtifact?: BuiltServerModuleOutputLike | undefined;
@@ -2663,10 +2675,10 @@ async function loadBundledMiddlewareModule(options: {
     }));
 
   return importAppRouterSourceModule<MiddlewareModule>({
-    ...(options.serverModuleCacheVersion === undefined
+    ...((options.serverModuleCacheVersion ?? options.devServerModuleCacheVersion) === undefined
       ? {}
       : {
-          cacheKey: `middleware:${options.file}:${options.serverModuleCacheVersion}:${memoizedHashText(compiled)}:${viteDefineCacheKey(options.define)}:${vitePluginsCacheKey(options.vitePlugins)}`,
+          cacheKey: `middleware:${options.serverModuleCacheVersion === undefined ? "dev" : "build"}:${options.file}:${options.serverModuleCacheVersion ?? options.devServerModuleCacheVersion}:${memoizedHashText(compiled)}:${viteDefineCacheKey(options.define)}:${vitePluginsCacheKey(options.vitePlugins)}`,
         }),
     code: compiled,
     define: options.define,
@@ -4447,6 +4459,7 @@ async function loadRouteData(options: {
   code: string;
   context: RouteDataContext;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   filename: string;
   importPolicy?: AppRouterImportPolicy | undefined;
   serverModules?: ReadonlyMap<string, BuiltServerModuleArtifact> | undefined;
@@ -4474,6 +4487,7 @@ async function loadRouteDataWithInstrumentation(options: {
   code: string;
   context: RouteDataContext;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   filename: string;
   importPolicy?: AppRouterImportPolicy | undefined;
   instrumentation?: RouterInstrumentation | undefined;
@@ -4514,16 +4528,19 @@ async function loadRouteLoaderModule(options: {
   appDir: string;
   code: string;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   filename: string;
   importPolicy?: AppRouterImportPolicy | undefined;
   serverModules?: ReadonlyMap<string, BuiltServerModuleArtifact> | undefined;
   serverModuleCacheVersion?: string | undefined;
   vitePlugins?: readonly PluginOption[] | undefined;
 }): Promise<RouteLoaderModule> {
+  const moduleCacheVersion =
+    options.serverModuleCacheVersion ?? options.devServerModuleCacheVersion;
   const cacheKey =
-    options.serverModuleCacheVersion === undefined
+    moduleCacheVersion === undefined
       ? undefined
-      : `${options.appDir}\0${options.filename}\0${options.serverModuleCacheVersion}\0${memoizedHashText(options.code)}\0${importPolicyCacheKey(options.importPolicy)}\0${viteDefineCacheKey(options.define)}\0${vitePluginsCacheKey(options.vitePlugins)}`;
+      : `${options.serverModuleCacheVersion === undefined ? "dev" : "build"}\0${options.appDir}\0${options.filename}\0${moduleCacheVersion}\0${memoizedHashText(options.code)}\0${importPolicyCacheKey(options.importPolicy)}\0${viteDefineCacheKey(options.define)}\0${vitePluginsCacheKey(options.vitePlugins)}`;
 
   if (cacheKey !== undefined) {
     const cached = readRouterRuntimeCacheEntry(
@@ -4602,6 +4619,7 @@ async function loadBundledRouteLoaderModule(options: {
   appDir: string;
   code: string;
   define?: UserConfig["define"] | undefined;
+  devServerModuleCacheVersion?: string | undefined;
   filename: string;
   importPolicy?: AppRouterImportPolicy | undefined;
   prebuiltArtifact?: BuiltServerModuleOutputLike | undefined;
@@ -4632,10 +4650,10 @@ async function loadBundledRouteLoaderModule(options: {
     }));
 
   return await importAppRouterSourceModule<RouteLoaderModule>({
-    ...(options.serverModuleCacheVersion === undefined
+    ...((options.serverModuleCacheVersion ?? options.devServerModuleCacheVersion) === undefined
       ? {}
       : {
-          cacheKey: `loader:${options.filename}:${options.serverModuleCacheVersion}:${memoizedHashText(code)}:${viteDefineCacheKey(options.define)}`,
+          cacheKey: `loader:${options.serverModuleCacheVersion === undefined ? "dev" : "build"}:${options.filename}:${options.serverModuleCacheVersion ?? options.devServerModuleCacheVersion}:${memoizedHashText(code)}:${viteDefineCacheKey(options.define)}:${vitePluginsCacheKey(options.vitePlugins)}`,
         }),
     code,
     define: options.define,