@rangojs/router 0.16.0 → 0.18.0

package/src/vite/plugins/use-cache-transform.ts

@@ -16,14 +16,18 @@
  * - transformHoistInlineDirective() for function-level hoisting
  */
 
-import type { Plugin } from "vite";
+import type { Plugin, Rollup } from "vite";
 import type { ModuleExportMeta } from "@vitejs/plugin-rsc/transforms";
 import path from "node:path";
-import MagicString from "magic-string";
 import { normalizePath, hashId } from "./expose-id-utils.js";
-import { createRangoDebugger, createCounter, NS } from "../debug.js";
+import type { Counter } from "../debug.js";
 
-const debug = createRangoDebugger(NS.transform);
+// No static import of `magic-string` or `../debug.js` (the `debug` package):
+// `rangoUseCacheTransform()` bundles this module into `dist/testing/vitest.js`,
+// whose static imports are node builtins only, and every package it needs
+// loads lazily, as `rangoUseClientTransform()`'s `vite` and plugin-rsc
+// imports do. src/__tests__/installed-vitest-config.test.ts loads that file
+// from a fixture holding only `package.json` and `dist/`.
 
 const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 
@@ -33,12 +37,13 @@ const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
 
 export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
 
-export function useCacheTransform(): Plugin {
+/**
+ * @param counter `rango:transform` timing counter, created by `rango()`
+ *   (`createCounter` in ../debug.js); omitted when debugging is off.
+ */
+export function useCacheTransform(counter?: Counter): Plugin {
   let projectRoot = "";
   let isBuild = false;
-  let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null =
-    null;
-  const counter = createCounter(debug, "use-cache");
 
   return {
     name: "@rangojs/router:use-cache",
@@ -56,75 +61,15 @@ export function useCacheTransform(): Plugin {
     async transform(code, id) {
       // Only process in RSC environment
       if (this.environment?.name !== "rsc") return;
-
-      // Quick bail: no "use cache" in source
-      if (!code.includes("use cache")) return;
-
-      // Skip node_modules and virtual modules
-      if (id.includes("/node_modules/") || id.startsWith("\0")) return;
-
-      // Only JS/TS files
-      if (!/\.(tsx?|jsx?|mjs)$/.test(id)) return;
+      if (!isUseCacheCandidate(code, id)) return;
 
       const start = counter ? performance.now() : 0;
       try {
-        if (!rscTransforms) {
-          try {
-            rscTransforms = await import("@vitejs/plugin-rsc/transforms");
-          } catch {
-            return;
-          }
-        }
-
-        const {
-          hasDirective,
-          transformWrapExport,
-          transformHoistInlineDirective,
-        } = rscTransforms;
-
-        let ast: any;
-        try {
-          const { parseAst } = await import("vite");
-          ast = parseAst(code, { lang: "tsx" });
-        } catch {
-          return;
-        }
-
-        // plugin-rsc 0.5.34 `matchDirective` does `stmt.directive.match(...)`
-        // after `"directive" in node`. Vite/oxc parseAst now emits
-        // `directive: null` on ordinary ExpressionStatements, so a file that
-        // mixes a `"use cache"` function with a sibling handler whose first
-        // statement is an expression throws and the wrap is dropped.
-        stripNullDirectiveFields(ast);
-
-        const filePath = normalizePath(path.relative(projectRoot, id));
-        const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
-
-        if (hasDirective(ast.body, "use cache")) {
-          return transformFileLevelUseCache(
-            code,
-            ast,
-            filePath,
-            id,
-            isBuild,
-            isLayoutOrTemplate,
-            transformWrapExport,
-            hasDirective,
-          );
-        }
-
-        const functionResult = transformFunctionLevelUseCache(
-          code,
-          ast,
-          filePath,
-          id,
+        return await transformUseCache(code, id, {
+          root: projectRoot,
           isBuild,
-          transformHoistInlineDirective,
-        );
-
-        warnOnNearMissDirectives(ast, id, this.warn.bind(this));
-
-        if (functionResult) return functionResult;
+          warn: (message) => this.warn(message),
+        });
       } finally {
         counter?.record(id, performance.now() - start);
       }
@@ -132,7 +77,105 @@ export function useCacheTransform(): Plugin {
   };
 }
 
-function transformFileLevelUseCache(
+/** Options for {@link transformUseCache}. */
+export interface UseCacheTransformOptions {
+  /** Root the ids are relative to (Vite's `config.root`). */
+  root: string;
+  /** Build ids hash the path (`hashId`); dev ids are `<path>#<export>`. */
+  isBuild: boolean;
+  /** Sink for the near-miss directive warning. */
+  warn: (message: string) => void;
+  /**
+   * Called when `@vitejs/plugin-rsc/transforms` fails to load; the module is
+   * then left unwrapped. The rango plugin omits it (skip silently).
+   */
+  onTransformsError?: (error: unknown) => void;
+}
+
+/** Whether a module may carry a `"use cache"` directive the transform wraps. */
+export function isUseCacheCandidate(code: string, id: string): boolean {
+  return (
+    // Quick bail: no "use cache" in source
+    code.includes("use cache") &&
+    // Skip node_modules and virtual modules
+    !id.includes("/node_modules/") &&
+    !id.startsWith("\0") &&
+    // Only JS/TS files
+    /\.(tsx?|jsx?|mjs)$/.test(id)
+  );
+}
+
+let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null = null;
+
+/**
+ * Wrap a module's `"use cache"` functions with `registerCachedFunction`. The
+ * rango plugin runs it in the rsc environment; `rangoUseCacheTransform()`
+ * (testing/vitest.ts) runs it in a Vitest project, whose environment is `ssr`.
+ * Call it only for an {@link isUseCacheCandidate} module.
+ */
+export async function transformUseCache(
+  code: string,
+  id: string,
+  options: UseCacheTransformOptions,
+): Promise<{ code: string; map: Rollup.ExistingRawSourceMap } | undefined> {
+  if (!rscTransforms) {
+    try {
+      rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+    } catch (error) {
+      options.onTransformsError?.(error);
+      return;
+    }
+  }
+
+  const { hasDirective, transformWrapExport, transformHoistInlineDirective } =
+    rscTransforms;
+
+  let ast: any;
+  try {
+    const { parseAst } = await import("vite");
+    ast = parseAst(code, { lang: "tsx" });
+  } catch {
+    return;
+  }
+
+  // plugin-rsc 0.5.34 `matchDirective` does `stmt.directive.match(...)`
+  // after `"directive" in node`. Vite/oxc parseAst now emits
+  // `directive: null` on ordinary ExpressionStatements, so a file that
+  // mixes a `"use cache"` function with a sibling handler whose first
+  // statement is an expression throws and the wrap is dropped.
+  stripNullDirectiveFields(ast);
+
+  const filePath = normalizePath(path.relative(options.root, id));
+  const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+
+  if (hasDirective(ast.body, "use cache")) {
+    return transformFileLevelUseCache(
+      code,
+      ast,
+      filePath,
+      id,
+      options.isBuild,
+      isLayoutOrTemplate,
+      transformWrapExport,
+      hasDirective,
+    );
+  }
+
+  const functionResult = transformFunctionLevelUseCache(
+    code,
+    ast,
+    filePath,
+    id,
+    options.isBuild,
+    transformHoistInlineDirective,
+  );
+
+  warnOnNearMissDirectives(ast, id, options.warn);
+
+  if (functionResult) return functionResult;
+}
+
+async function transformFileLevelUseCache(
   code: string,
   ast: any,
   filePath: string,
@@ -193,6 +236,7 @@ function transformFileLevelUseCache(
   }
 
   if (exportNames.length === 0) {
+    const { default: MagicString } = await import("magic-string");
     const s = new MagicString(code);
     const directive = findFileLevelDirective(ast);
     if (directive) {

package/src/vite/rango.ts

@@ -45,7 +45,7 @@ import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
 import { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
 import { createRouterDiscoveryPlugin } from "./router-discovery.js";
 import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
-import { createRangoDebugger, NS } from "./debug.js";
+import { createCounter, createRangoDebugger, NS } from "./debug.js";
 
 const debugConfig = createRangoDebugger(NS.config);
 
@@ -100,7 +100,7 @@ export { hasUseClientDirective };
  *   plugins: [
  *     react(),
  *     rango({ preset: 'cloudflare' }),
- *     cloudflare({ viteEnvironment: { name: 'rsc' } }),
+ *     cloudflare({ viteEnvironment: { name: 'rsc', childEnvironments: ['ssr'] } }),
  *   ],
  * });
  * ```
@@ -565,7 +565,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
-  plugins.push(useCacheTransform());
+  plugins.push(
+    useCacheTransform(
+      createCounter(createRangoDebugger(NS.transform), "use-cache"),
+    ),
+  );
   plugins.push(exposeInternalIds());
   plugins.push(exposeRouterId());
   plugins.push(createVersionPlugin());

package/src/vite/router-discovery.ts

@@ -6,7 +6,7 @@
  * generation, virtual module codegen, and bundle post-processing.
  */
 
-import type { Plugin } from "vite";
+import type { Plugin, ViteDevServer } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
@@ -177,8 +177,9 @@ const injectedShellNotReadyPaths = new Set<string>();
  * - Build: hashed IDs (forceBuild), hashClientRefs for production bundles
  *
  * Returns the ViteDevServer instance. Callers access .environments.rsc as needed.
+ * @internal Exported for tests.
  */
-async function createTempRscServer(
+export async function createTempRscServer(
   state: DiscoveryState,
   options: {
     forceBuild?: boolean;
@@ -195,7 +196,7 @@ async function createTempRscServer(
      */
     realSsrEntry?: boolean;
   } = {},
-) {
+): Promise<ViteDevServer> {
   // Install the Node ESM loader hook before any module evaluation so
   // `cloudflare:*` specifiers in externalized/loader-delegated modules
   // (e.g. packages plugin-rsc marks as external) resolve to stubs
@@ -216,7 +217,16 @@ async function createTempRscServer(
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
-    server: { middlewareMode: true },
+    server: {
+      middlewareMode: true,
+      // Build mode: no file watching. buildStart installs the per-router tries
+      // into this realm and runShellPrerenderPhase reuses it after the bundles
+      // are written. A watched write in between (writeRouteTypesFiles' own
+      // <router>.named-routes.gen.ts, which every router file imports) can
+      // make Vite full-reload the RSC runner; the shell phase then matches in
+      // a fresh realm with no tries and a root path("/*") wins (#947).
+      ...(options.forceBuild ? { watch: null } : {}),
+    },
     appType: "custom",
     logLevel: "silent",
     resolve: resolveConfig,