@rangojs/router 0.12.0 → 0.12.2

package/dist/testing/vitest.js

@@ -1,8 +1,21 @@
 // src/testing/vitest.ts
-import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
 function here(relativeFromRoot) {
   return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
 }
+var RSD_SERVER_EDGE_SPEC = "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+var requireFromHere = createRequire(
+  import.meta.url
+);
+function resolveFromRouter(spec) {
+  try {
+    return requireFromHere.resolve(spec);
+  } catch {
+    return void 0;
+  }
+}
+var rsdServerEdgePath = resolveFromRouter(RSD_SERVER_EDGE_SPEC);
 function rangoTestAliases(opts = {}) {
   const aliases = [
     // Real impls (index.rsc.ts) for the bare specifier ONLY — exact regex so
@@ -18,6 +31,12 @@ function rangoTestAliases(opts = {}) {
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts")
     }
   ];
+  if (rsdServerEdgePath) {
+    aliases.push({
+      find: RSD_SERVER_EDGE_SPEC,
+      replacement: rsdServerEdgePath
+    });
+  }
   if (opts.preset === "cloudflare") {
     aliases.push(
       {
@@ -63,8 +82,9 @@ function rangoUseClientTransform() {
       });
       if (!result) return void 0;
       const { output } = result;
+      const rsdHref = rsdServerEdgePath ? pathToFileURL(rsdServerEdgePath).href : RSD_SERVER_EDGE_SPEC;
       output.prepend(
-        `import * as $$RangoRSD from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+        `import * as $$RangoRSD from ${JSON.stringify(rsdHref)};
 `
       );
       return {

package/dist/types/vite/plugins/vercel-output.d.ts

@@ -28,9 +28,11 @@
  *      type:module in scope the deployed (isolated) function loads them as
  *      CommonJS and fails on the first `import`.
  *
- * The launcher is bundled with srvx (the Web->Node streaming bridge, a
- * @rangojs/router dependency) and @vercel/functions (resolved from the app)
- * inlined, keeping the RSC bundle a runtime-relative external.
+ * The launcher is bundled with rolldown (Vite 8's bundler — a production
+ * dependency of `vite`, resolved through the app's vite install) so a
+ * standalone consumer does not need `esbuild`. srvx (the Web->Node streaming
+ * bridge, a @rangojs/router dependency) and @vercel/functions (resolved from
+ * the app) are inlined; the RSC bundle stays a runtime-relative external.
  *
  * Timing: this runs in the `buildApp` hook (order "post"), which fires once
  * after every environment has built, so dist/{client,rsc,ssr} all exist.
@@ -41,6 +43,23 @@
  */
 import type { Plugin } from "vite";
 import type { RangoVercelOptions, VercelPresetOptions } from "../plugin-types.js";
+/**
+ * Resolve rolldown through the app's vite install (rolldown is a production
+ * dependency of Vite 8, unlike esbuild which is only an optional peer). Fall
+ * back to the app root, then the plugin's own vite, so a hoisted or
+ * workspace copy still works. Issue #785: the previous "esbuild ships with
+ * Vite" path broke standalone consumers on Vite 8.
+ */
+export declare function resolveRolldownPath(root: string): string;
+/**
+ * Bundle the Node launcher into `funcDir/index.mjs`: srvx + @vercel/functions
+ * inlined, `./rsc/index.js` left as a runtime-relative external.
+ */
+export declare function bundleVercelLauncher(opts: {
+    root: string;
+    funcDir: string;
+    srvxNodePath: string;
+}): Promise<void>;
 /**
  * Reject a non-Node runtime for the vercel preset. The preset only emits a Node
  * serverless function (launcherType "Nodejs", bundled Node APIs, response

package/dist/vite/index.js

@@ -3746,7 +3746,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.12.0",
+  version: "0.12.2",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -5682,6 +5682,7 @@ import { existsSync as existsSync5 } from "node:fs";
 import { resolve as resolve5, join as join4 } from "node:path";
 import { createRequire as createRequire2 } from "node:module";
 import { pathToFileURL } from "node:url";
+var VIRTUAL_LAUNCHER_ID = "\0rango-vercel-launcher";
 var LAUNCHER_SOURCE = `import { toNodeHandler } from "srvx/node";
 import { waitUntil } from "@vercel/functions";
 import rscHandler from "./rsc/index.js";
@@ -5701,6 +5702,99 @@ const fetchHandler = (request) =>
 
 export default toNodeHandler(fetchHandler);
 `;
+function resolveRolldownPath(root) {
+  const appRequire = createRequire2(join4(root, "package.json"));
+  const rangoRequire = createRequire2(import.meta.url);
+  const attempts = [
+    () => createRequire2(appRequire.resolve("vite")).resolve("rolldown"),
+    () => appRequire.resolve("rolldown"),
+    () => createRequire2(rangoRequire.resolve("vite")).resolve("rolldown"),
+    () => rangoRequire.resolve("rolldown")
+  ];
+  for (const attempt of attempts) {
+    try {
+      return attempt();
+    } catch {
+    }
+  }
+  throw new Error(
+    '[rango] preset "vercel" requires "rolldown" to bundle the function launcher. Vite 8 depends on it; reinstall dependencies.'
+  );
+}
+async function bundleVercelLauncher(opts) {
+  const { root, funcDir, srvxNodePath } = opts;
+  const appRequire = createRequire2(join4(root, "package.json"));
+  let vercelFunctionsPath;
+  try {
+    vercelFunctionsPath = appRequire.resolve("@vercel/functions");
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).'
+    );
+  }
+  let rolldownModule;
+  try {
+    rolldownModule = await import(pathToFileURL(resolveRolldownPath(root)).href);
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel" requires "rolldown" to bundle the function launcher. Vite 8 depends on it; reinstall dependencies.'
+    );
+  }
+  const rolldownFn = rolldownModule.rolldown ?? rolldownModule.default?.rolldown;
+  if (typeof rolldownFn !== "function") {
+    throw new Error('[rango] preset "vercel": could not load rolldown().');
+  }
+  let bundle;
+  try {
+    bundle = await rolldownFn({
+      input: VIRTUAL_LAUNCHER_ID,
+      cwd: root,
+      platform: "node",
+      logLevel: "silent",
+      resolve: {
+        alias: {
+          "srvx/node": srvxNodePath,
+          "@vercel/functions": vercelFunctionsPath
+        }
+      },
+      plugins: [
+        {
+          name: "rango-vercel-launcher",
+          resolveId(id) {
+            if (id === VIRTUAL_LAUNCHER_ID) return VIRTUAL_LAUNCHER_ID;
+            if (id === "./rsc/index.js") {
+              return { id: "./rsc/index.js", external: true };
+            }
+            return null;
+          },
+          load(id) {
+            if (id === VIRTUAL_LAUNCHER_ID) return LAUNCHER_SOURCE;
+            return null;
+          }
+        }
+      ]
+    });
+    await bundle.write({
+      file: join4(funcDir, "index.mjs"),
+      format: "esm",
+      exports: "default",
+      // @vercel/functions (and srvx) may contain dynamic import(); the
+      // launcher must stay a single index.mjs — Vercel's handler field
+      // points at that one file.
+      codeSplitting: false
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/@vercel\/functions/.test(message)) {
+      throw new Error(
+        '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).\n' + message
+      );
+    }
+    throw error;
+  } finally {
+    await bundle?.close();
+  }
+}
 function assertVercelNodeRuntime(runtime2) {
   if (runtime2 != null && !runtime2.startsWith("nodejs")) {
     throw new Error(
@@ -5788,66 +5882,7 @@ async function assemble(root, options, assetsDir, publicDir) {
       '[rango] preset "vercel" requires "srvx" (a dependency of @rangojs/router). Reinstall dependencies.'
     );
   }
-  const appRequire = createRequire2(join4(root, "package.json"));
-  const resolveEsbuildPath = () => {
-    try {
-      const viteRequire = createRequire2(appRequire.resolve("vite"));
-      return viteRequire.resolve("esbuild");
-    } catch {
-    }
-    try {
-      return appRequire.resolve("esbuild");
-    } catch {
-    }
-    return rangoRequire.resolve("esbuild");
-  };
-  let esbuildModule;
-  try {
-    esbuildModule = await import(pathToFileURL(resolveEsbuildPath()).href);
-  } catch {
-    throw new Error(
-      '[rango] preset "vercel" requires "esbuild" to bundle the function launcher. It ships with Vite; reinstall dependencies (or add esbuild to your app dependencies).'
-    );
-  }
-  const esbuildBuild = esbuildModule.build ?? esbuildModule.default?.build;
-  if (typeof esbuildBuild !== "function") {
-    throw new Error('[rango] preset "vercel": could not load esbuild.build.');
-  }
-  try {
-    await esbuildBuild({
-      stdin: {
-        contents: LAUNCHER_SOURCE,
-        resolveDir: root,
-        sourcefile: "func-entry.mjs",
-        loader: "js"
-      },
-      outfile: join4(funcDir, "index.mjs"),
-      bundle: true,
-      format: "esm",
-      platform: "node",
-      target: "node18",
-      alias: { "srvx/node": srvxNodePath },
-      plugins: [
-        {
-          name: "external-rsc-entry",
-          setup(b) {
-            b.onResolve({ filter: /^\.\/rsc\/index\.js$/ }, () => ({
-              path: "./rsc/index.js",
-              external: true
-            }));
-          }
-        }
-      ]
-    });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (/@vercel\/functions/.test(message)) {
-      throw new Error(
-        '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).\n' + message
-      );
-    }
-    throw error;
-  }
+  await bundleVercelLauncher({ root, funcDir, srvxNodePath });
   await writeFile(
     join4(funcDir, "package.json"),
     JSON.stringify({ type: "module" }, null, 2) + "\n"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/catalog.json

@@ -197,7 +197,7 @@
     },
     {
       "name": "react-compiler",
-      "description": "Enable the React Compiler in a Rango app the @vitejs/plugin-rsc way — a separate @rolldown/plugin-babel running reactCompilerPreset(), ordered after react() and before the plugin that supplies @vitejs/plugin-rsc. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, or is unsure why server components aren't being compiled.",
+      "description": "Enable the React Compiler in a Rango app with @vitejs/plugin-react 6.1's native `compiler` option (oxc-transform-react) — one flag, client components only, no Babel. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, sees an unmet-peer / ERESOLVE on oxc-transform-react, or is unsure why server components aren't being compiled.",
       "argumentHint": "",
       "path": "skills/react-compiler/SKILL.md"
     },

package/skills/rango/SKILL.md

@@ -289,7 +289,7 @@ Grouped by concern — read when you need to…
 | `/view-transitions` | React View Transitions on layouts, routes, and parallel slots                                                                      |
 | `/defer-hydration`  | Full body HTML in the PPR shell + hydration off the critical path (gated Suspense boundary, content-as-fallback)                   |
 | `/breadcrumbs`      | Built-in Breadcrumbs handle for breadcrumb navigation                                                                              |
-| `/react-compiler`   | Enable React Compiler (opt-in) the vite-rsc way; client-only scope                                                                 |
+| `/react-compiler`   | Enable React Compiler (opt-in) via plugin-react's native `compiler` option; client-only scope                                      |
 
 **Observability & production health**:
 

package/skills/react-compiler/SKILL.md

@@ -1,45 +1,49 @@
 ---
 name: react-compiler
-description: Enable the React Compiler in a Rango app the @vitejs/plugin-rsc way — a separate @rolldown/plugin-babel running reactCompilerPreset(), ordered after react() and before the plugin that supplies @vitejs/plugin-rsc. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, or is unsure why server components aren't being compiled.
+description: Enable the React Compiler in a Rango app with @vitejs/plugin-react 6.1's native `compiler` option (oxc-transform-react) — one flag, client components only, no Babel. Use when a consumer wants to turn React Compiler on, hits the dead plugin-react v6 `react({ babel })` path, sees an unmet-peer / ERESOLVE on oxc-transform-react, or is unsure why server components aren't being compiled.
 argument-hint:
 ---
 
 # React Compiler
 
-React Compiler is **opt-in** in Rango. The plugin pipeline is fully compatible —
-you just add one more plugin. The catch on a current Rango stack (Vite 8 +
-`@vitejs/plugin-react` v6) is that **v6 dropped its internal Babel for oxc**, so
-the way the React docs and most blog posts show it — `react({ babel: { plugins:
-[...] } })` — silently does nothing. The compiler has to be its own top-level
-plugin.
+React Compiler is **opt-in** in Rango, and it is one option on the plugin you
+already have: `@vitejs/plugin-react` 6.1 ships a native React Compiler behind
+`react({ compiler: true })`, backed by
+[`oxc-transform-react`](https://www.npmjs.com/package/oxc-transform-react),
+Oxc's Rust port of the compiler. No Babel, no extra plugin, no ordering rules.
+Upstream marks the option experimental; the previous Babel wiring still works
+and is kept below as the [fallback](#babel-fallback).
 
 ## The shape (read first)
 
-- The compiler is a **Babel** plugin, run via
-  [`@rolldown/plugin-babel`](https://www.npmjs.com/package/@rolldown/plugin-babel)
-  with `reactCompilerPreset()` from `@vitejs/plugin-react`.
-- **Ordering is load-bearing:** put `babel(...)` **after `react()`** and
-  **before the plugin that supplies `@vitejs/plugin-rsc`**. In a default Rango
-  app that plugin is `rango()` itself; in a Cloudflare app it is
-  `@cloudflare/vite-plugin`.
-- **It is client-only.** `reactCompilerPreset()` gates itself to the client
-  environment. Server/RSC components are not compiled, and that is the upstream
-  example's behavior — not a Rango limitation. See
+- **One option:** `react({ compiler: true })`. Needs `@vitejs/plugin-react` 6.1+
+  and its optional peer `oxc-transform-react`.
+- **It is client-only.** plugin-react runs the compiler only in environments
+  whose `consumer` is not `"server"`. Server/RSC components are not compiled,
+  and that is plugin-react's contract — not a Rango limitation. See
   [What gets compiled](#what-gets-compiled-client-only).
-- **Rango's build-time prerender is unaffected.** You do not need to do anything
-  special. See [Prerender](#interaction-with-build-time-prerender).
+- **It owns JSX and Fast Refresh too.** With `compiler` on, plugin-react hands
+  TypeScript, JSX and Fast Refresh to the same native pass and disables Vite's
+  built-in refresh injection. Nothing to configure, and dev line numbers still
+  point at your source.
+- **Rango's build-time prerender is unaffected.** See
+  [Prerender](#interaction-with-build-time-prerender).
 
 ## Step 1: Install
 
 ```bash
-pnpm add -D @rolldown/plugin-babel @babel/core babel-plugin-react-compiler
-# TypeScript users also want the Babel core types:
-pnpm add -D @types/babel__core
+pnpm add -D oxc-transform-react@^0.145.0
 ```
 
+Take the range from `@vitejs/plugin-react`'s `peerDependencies` (`^0.145.0` for
+6.1.x) rather than npm's latest. `oxc-transform-react` cuts a new minor every
+couple of weeks and plugin-react widens its range in its own releases, so a newer
+binding shows up as an unmet-peer warning under pnpm and an `ERESOLVE` error
+under npm (vitejs/vite-plugin-react#1437). Bump both together.
+
 React 19 ships `react/compiler-runtime` in-tree, so there is **no** extra runtime
-to install and **no** `target` option to set. Only pass `target: '17' | '18'` to
-`reactCompilerPreset()` if you are on an older React.
+to install and **no** `target` option to set. Only pass `target: '17' | '18'` if
+you are on an older React.
 
 ## Step 2: Wire it in
 
@@ -48,16 +52,11 @@ to install and **no** `target` option to set. Only pass `target: '17' | '18'` to
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-import react, { reactCompilerPreset } from "@vitejs/plugin-react";
-import babel from "@rolldown/plugin-babel";
+import react from "@vitejs/plugin-react";
 import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
-  plugins: [
-    react(),
-    babel({ presets: [reactCompilerPreset()] }),
-    rango(), // supplies @vitejs/plugin-rsc
-  ],
+  plugins: [react({ compiler: true }), rango()],
 });
 ```
 
@@ -66,29 +65,29 @@ export default defineConfig({
 ```ts
 // vite.config.ts
 import { cloudflare } from "@cloudflare/vite-plugin";
-import react, { reactCompilerPreset } from "@vitejs/plugin-react";
-import babel from "@rolldown/plugin-babel";
+import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
   plugins: [
-    react(),
-    babel({ presets: [reactCompilerPreset()] }),
+    react({ compiler: true }),
     rango({ preset: "cloudflare" }),
     cloudflare({
       /* ... */
-    }), // supplies @vitejs/plugin-rsc
+    }),
   ],
 });
 ```
 
+Both layouts keep `react()` ahead of `rango()` / `cloudflare()`, which is what
+Rango's own e2e apps run.
+
 ## What gets compiled (client-only)
 
-`reactCompilerPreset()` carries
-`rolldown.applyToEnvironmentHook: (env) => env.config.consumer === "client"`, so
-even though the babel plugin is top-level, the transform runs **only in the
-`client` environment**:
+plugin-react's `vite:react-compiler` transform runs in every environment, but
+passes `reactCompiler: false` whenever `environment.config.consumer === "server"`.
+Server environments only get the TypeScript/JSX pass:
 
 | Environment | `consumer` | Compiled? |
 | ----------- | ---------- | --------- |
@@ -96,43 +95,53 @@ even though the babel plugin is top-level, the transform runs **only in the
 | ssr         | `server`   | No        |
 | rsc         | `server`   | No        |
 
-This matches the upstream `@vitejs/plugin-rsc` example. If you genuinely need to
-compile **server** components, you would have to invoke
-`babel-plugin-react-compiler` yourself without the preset's
-`applyToEnvironmentHook` — that is outside what the example does and is not
+If you genuinely need to compile **server** components, the native option cannot
+do it; you would have to run `babel-plugin-react-compiler` yourself. That is not
 covered here.
 
 ## Options
 
-`reactCompilerPreset()` forwards to `babel-plugin-react-compiler`:
+`compiler` takes `true` or the React Compiler configuration plus one plugin-level
+flag:
+
+| Option                          | Effect                                                                                                                                         |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compilationMode: 'annotation'` | Compile only components marked with the `"use memo"` directive, not every eligible one                                                         |
+| `target: '17' \| '18'`          | Emit `react-compiler-runtime` calls for React < 19. Omit on React 19+.                                                                         |
+| `logDiagnostics: true`          | Log recoverable compiler diagnostics (why a component was skipped) through Vite. Default `false`. Fatal diagnostics always fail the transform. |
 
-| Option                          | Effect                                                                                 |
-| ------------------------------- | -------------------------------------------------------------------------------------- |
-| `compilationMode: 'annotation'` | Compile only components marked with the `"use memo"` directive, not every eligible one |
-| `target: '17' \| '18'`          | Emit `react-compiler-runtime` calls for React < 19. Omit on React 19+.                 |
+`logDiagnostics` can only relay what the binding reports. `oxc-transform-react`
+0.145.x, the range plugin-react 6.1 declares, reports bail-out reasons. 0.148.0
+dropped them (oxc-project/oxc#26318), so the flag goes silent once plugin-react's
+peer range moves past it; 0.146 and 0.147 still report but need a later
+plugin-react. Callback-valued Babel
+options (`logger`, function-valued `sources`) do not exist on the native path;
+`sources` takes an array of filename substrings.
 
 ## Interaction with build-time prerender
 
 Nothing to configure. Rango's discovery/prerender step runs a throwaway temp Vite
 server (`createTempRscServer`) that forwards only your **resolution** plugins
-(`resolveId` / `load`). A pure transform plugin like `@rolldown/plugin-babel` is
-intentionally **not** forwarded — and that is correct: the temp runner only
-produces **data** (serialized Flight payloads + the route manifest), not shipped
-code, and React Compiler is a memoization-only transform that does not change
-rendered output. Your shipped client bundle still gets compiled, because the
-babel plugin lives in your app's top-level plugin array alongside `react()`.
+(`resolveId` / `load`) and denies every `vite:*` plugin, so `vite:react-compiler`
+never runs there. That is correct: the temp runner only produces **data**
+(serialized Flight payloads + the route manifest), not shipped code, and React
+Compiler is a memoization-only transform that does not change rendered output.
+Your shipped client bundle is compiled by the `react({ compiler: true })` in your
+app's own plugin array.
 
 ## Step 3: Verify the compiler actually ran
 
-A compiled module imports the cache allocator from `react/compiler-runtime` and
+The native compiler emits the same shape as `babel-plugin-react-compiler`. A
+compiled module imports the cache allocator from `react/compiler-runtime` and
 calls `_c(n)`. Those two appear in **every** compiled module, so they are the
-reliable per-module signal in dev:
+reliable per-module signal in dev, and a compiled module also carries Fast
+Refresh's `$RefreshReg$(...)` registration:
 
 ```bash
 pnpm dev
 # fetch any client component module straight from Vite and look for the markers:
 curl -s "http://localhost:5173/src/components/SomeClientComponent.tsx" \
-  | grep -E "compiler-runtime|_c\("
+  | grep -E "compiler-runtime|_c\(|\\\$RefreshReg\\\$\("
 ```
 
 For a production build, grep the built client bundle for the compiler's
@@ -150,19 +159,48 @@ also defines that symbol once with a single `=` assignment, so count comparisons
 not the bare string.) Run the same grep over `dist/rsc` / `dist/ssr` and you
 should find **none** — that is the client-only contract.
 
+Output is not byte-identical to Babel's: the port tracks React's experimental
+compiler channel, so a handful of components memoize a different number of
+values, and comments inside a compiled function body are dropped. Neither changes
+rendered output.
+
+## Babel fallback
+
+On `@vitejs/plugin-react` < 6.1, or if you need a Babel-only compiler option, the
+previous wiring still works: a top-level
+[`@rolldown/plugin-babel`](https://www.npmjs.com/package/@rolldown/plugin-babel)
+running `reactCompilerPreset()` from `@vitejs/plugin-react`, placed **after
+`react()`** and **before the plugin that supplies `@vitejs/plugin-rsc`**. The
+preset gates itself to `consumer === "client"`, so the client-only contract is
+the same. Do not combine it with `compiler: true`.
+
+```bash
+pnpm add -D @rolldown/plugin-babel @babel/core babel-plugin-react-compiler @types/babel__core
+```
+
+```ts
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import babel from "@rolldown/plugin-babel";
+
+// plugins: [react(), babel({ presets: [reactCompilerPreset()] }), rango()]
+```
+
 ## Troubleshooting
 
-| Symptom                                                               | Cause / fix                                                                                                                                 |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Nothing is compiled; no `compiler-runtime` import anywhere            | You used `react({ babel: { plugins: [...] } })`. plugin-react v6 has no internal Babel — add `@rolldown/plugin-babel` as its own plugin.    |
-| Client compiled, but server/RSC components are not                    | Expected. `reactCompilerPreset()` is client-only (see the table). Not a bug.                                                                |
-| `Cannot find module 'babel-plugin-react-compiler'` (or `@babel/core`) | Install the peer deps from Step 1; they are not bundled by `reactCompilerPreset()`.                                                         |
-| Build pulls in `react-compiler-runtime`                               | You set `target: '17'`/`'18'` on React 19. Drop `target` — React 19 ships `react/compiler-runtime` in-tree.                                 |
-| Output looks compiled but a component misbehaves                      | The component likely breaks the Rules of React. Fix the component, or scope the compiler with `compilationMode: 'annotation'` while you do. |
+| Symptom                                                                       | Cause / fix                                                                                                                                                                                             |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `React Compiler requires the optional oxc-transform-react package` on startup | Install it (Step 1). plugin-react checks in its `config` hook, so the error is immediate.                                                                                                               |
+| Nothing is compiled; no `compiler-runtime` import anywhere                    | You used `react({ babel: { plugins: [...] } })`. plugin-react v6 has no internal Babel — use `react({ compiler: true })`.                                                                               |
+| pnpm warns `unmet peer oxc-transform-react`, npm fails with `ERESOLVE`        | The binding is newer than plugin-react's peer range. Pin the range plugin-react declares.                                                                                                               |
+| Client compiled, but server/RSC components are not                            | Expected. The option is client-only (see the table). Not a bug.                                                                                                                                         |
+| `logDiagnostics: true` prints nothing                                         | You are on `oxc-transform-react` 0.148.0 or later, which dropped recoverable diagnostics. On plugin-react 6.1.x stay on 0.145.x; 0.146 and 0.147 also report, but need a later plugin-react peer range. |
+| Build pulls in `react-compiler-runtime`                                       | You set `target: '17'`/`'18'` on React 19. Drop `target` — React 19 ships `react/compiler-runtime` in-tree.                                                                                             |
+| Output looks compiled but a component misbehaves                              | The component likely breaks the Rules of React. Fix the component, or scope the compiler with `compilationMode: 'annotation'` while you do.                                                             |
 
 ## Reference
 
 A worked, tested wiring (dev + production e2e markers, incl. the client-only
-contract) lives in the `@rangojs/router` repository — not shipped in this
-package: `docs/react-compiler.md` and the `react-compiler.test.ts` files under
-`e2e/e2e-basic`, `tests/cloudflare-basic`, and `tests/vite-rsc-demo`.
+contract and the Fast Refresh check) lives in the `@rangojs/router` repository —
+not shipped in this package: `docs/react-compiler.md` and the
+`react-compiler.test.ts` files under `e2e/e2e-basic`, `tests/cloudflare-basic`,
+and `tests/vite-rsc-demo`.

package/skills/testing/setup.md

@@ -114,7 +114,7 @@ Scripts:
 - The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
 - The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
 - The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
-- Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`.
+- Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`. The transform's `registerClientReference` import is resolved from `@rangojs/router`'s `@vitejs/plugin-rsc` — the consumer does not need a direct plugin-rsc dependency.
 
 ## See also
 

package/src/testing/vitest.ts

@@ -76,7 +76,8 @@
  *   a focused include, or use e2e.
  */
 
-import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
 export interface TestAlias {
@@ -108,6 +109,32 @@ function here(relativeFromRoot: string): string {
   return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
 }
 
+/**
+ * Spec `rangoUseClientTransform` injects into `"use client"` modules. A
+ * consumer app does not depend on `@vitejs/plugin-rsc`, so the bare specifier
+ * is unresolvable from their `"use client"` files (cloudflare-basic
+ * `server-tree.rsc-test.tsx` on plugin-rsc 0.5.34). Resolve it from THIS
+ * module — `@rangojs/router` does depend on plugin-rsc — and alias / inject
+ * the absolute path.
+ */
+const RSD_SERVER_EDGE_SPEC: string =
+  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+
+const requireFromHere: ReturnType<typeof createRequire> = createRequire(
+  import.meta.url,
+);
+
+function resolveFromRouter(spec: string): string | undefined {
+  try {
+    return requireFromHere.resolve(spec);
+  } catch {
+    return undefined;
+  }
+}
+
+const rsdServerEdgePath: string | undefined =
+  resolveFromRouter(RSD_SERVER_EDGE_SPEC);
+
 /**
  * Build the `resolve.alias` entries a consumer's node/DOM Vitest project needs to
  * import a real @rangojs/router app's router/loaders/middleware. Spread into a
@@ -131,6 +158,12 @@ export function rangoTestAliases(
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
     },
   ];
+  if (rsdServerEdgePath) {
+    aliases.push({
+      find: RSD_SERVER_EDGE_SPEC,
+      replacement: rsdServerEdgePath,
+    });
+  }
 
   if (opts.preset === "cloudflare") {
     aliases.push(
@@ -292,10 +325,13 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
       });
       if (!result) return undefined;
       const { output } = result;
-      // The vendored server serializer is the one renderToFlightString uses;
-      // resolvable here under the react-server condition.
+      // Absolute file URL, not the bare specifier: the consumer's "use client"
+      // module cannot resolve @vitejs/plugin-rsc (it is a router dependency).
+      const rsdHref = rsdServerEdgePath
+        ? pathToFileURL(rsdServerEdgePath).href
+        : RSD_SERVER_EDGE_SPEC;
       output.prepend(
-        `import * as $$RangoRSD from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";\n`,
+        `import * as $$RangoRSD from ${JSON.stringify(rsdHref)};\n`,
       );
       return {
         code: output.toString(),

package/src/vite/plugins/vercel-output.ts

@@ -28,9 +28,11 @@
  *      type:module in scope the deployed (isolated) function loads them as
  *      CommonJS and fails on the first `import`.
  *
- * The launcher is bundled with srvx (the Web->Node streaming bridge, a
- * @rangojs/router dependency) and @vercel/functions (resolved from the app)
- * inlined, keeping the RSC bundle a runtime-relative external.
+ * The launcher is bundled with rolldown (Vite 8's bundler — a production
+ * dependency of `vite`, resolved through the app's vite install) so a
+ * standalone consumer does not need `esbuild`. srvx (the Web->Node streaming
+ * bridge, a @rangojs/router dependency) and @vercel/functions (resolved from
+ * the app) are inlined; the RSC bundle stays a runtime-relative external.
  *
  * Timing: this runs in the `buildApp` hook (order "post"), which fires once
  * after every environment has built, so dist/{client,rsc,ssr} all exist.
@@ -52,19 +54,30 @@ import type {
   VercelPresetOptions,
 } from "../plugin-types.js";
 
-// Minimal structural types for the esbuild API we use, resolved dynamically from
-// the app so @rangojs/router does not depend on esbuild's type package.
-interface EsbuildPluginBuild {
-  onResolve(
-    options: { filter: RegExp },
-    callback: () => { path: string; external: boolean },
-  ): void;
+// Minimal structural types for the rolldown API we use. Resolved dynamically
+// from the app's vite install so @rangojs/router does not depend on rolldown's
+// type package (same stance the previous esbuild path took).
+interface RolldownResolveResult {
+  id: string;
+  external?: boolean;
 }
-type EsbuildBuild = (options: Record<string, unknown>) => Promise<unknown>;
-interface EsbuildModule {
-  build?: EsbuildBuild;
-  default?: { build?: EsbuildBuild };
+interface RolldownBundle {
+  write: (output: {
+    file: string;
+    format: string;
+    exports: string;
+    codeSplitting?: boolean;
+  }) => Promise<unknown>;
+  close: () => Promise<void>;
 }
+interface RolldownModule {
+  rolldown?: (options: Record<string, unknown>) => Promise<RolldownBundle>;
+  default?: {
+    rolldown?: (options: Record<string, unknown>) => Promise<RolldownBundle>;
+  };
+}
+
+const VIRTUAL_LAUNCHER_ID = "\0rango-vercel-launcher";
 
 const LAUNCHER_SOURCE = `import { toNodeHandler } from "srvx/node";
 import { waitUntil } from "@vercel/functions";
@@ -86,6 +99,122 @@ const fetchHandler = (request) =>
 export default toNodeHandler(fetchHandler);
 `;
 
+/**
+ * Resolve rolldown through the app's vite install (rolldown is a production
+ * dependency of Vite 8, unlike esbuild which is only an optional peer). Fall
+ * back to the app root, then the plugin's own vite, so a hoisted or
+ * workspace copy still works. Issue #785: the previous "esbuild ships with
+ * Vite" path broke standalone consumers on Vite 8.
+ */
+export function resolveRolldownPath(root: string): string {
+  const appRequire = createRequire(join(root, "package.json"));
+  const rangoRequire = createRequire(import.meta.url);
+  const attempts: Array<() => string> = [
+    () => createRequire(appRequire.resolve("vite")).resolve("rolldown"),
+    () => appRequire.resolve("rolldown"),
+    () => createRequire(rangoRequire.resolve("vite")).resolve("rolldown"),
+    () => rangoRequire.resolve("rolldown"),
+  ];
+  for (const attempt of attempts) {
+    try {
+      return attempt();
+    } catch {
+      // Intentionally empty: try the next resolver.
+    }
+  }
+  throw new Error(
+    '[rango] preset "vercel" requires "rolldown" to bundle the function launcher. Vite 8 depends on it; reinstall dependencies.',
+  );
+}
+
+/**
+ * Bundle the Node launcher into `funcDir/index.mjs`: srvx + @vercel/functions
+ * inlined, `./rsc/index.js` left as a runtime-relative external.
+ */
+export async function bundleVercelLauncher(opts: {
+  root: string;
+  funcDir: string;
+  srvxNodePath: string;
+}): Promise<void> {
+  const { root, funcDir, srvxNodePath } = opts;
+  const appRequire = createRequire(join(root, "package.json"));
+  let vercelFunctionsPath: string;
+  try {
+    vercelFunctionsPath = appRequire.resolve("@vercel/functions");
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).',
+    );
+  }
+  let rolldownModule: RolldownModule;
+  try {
+    rolldownModule = (await import(
+      pathToFileURL(resolveRolldownPath(root)).href
+    )) as RolldownModule;
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel" requires "rolldown" to bundle the function launcher. Vite 8 depends on it; reinstall dependencies.',
+    );
+  }
+  const rolldownFn =
+    rolldownModule.rolldown ?? rolldownModule.default?.rolldown;
+  if (typeof rolldownFn !== "function") {
+    throw new Error('[rango] preset "vercel": could not load rolldown().');
+  }
+
+  let bundle: RolldownBundle | undefined;
+  try {
+    bundle = await rolldownFn({
+      input: VIRTUAL_LAUNCHER_ID,
+      cwd: root,
+      platform: "node",
+      logLevel: "silent",
+      resolve: {
+        alias: {
+          "srvx/node": srvxNodePath,
+          "@vercel/functions": vercelFunctionsPath,
+        },
+      },
+      plugins: [
+        {
+          name: "rango-vercel-launcher",
+          resolveId(id: string): string | RolldownResolveResult | null {
+            if (id === VIRTUAL_LAUNCHER_ID) return VIRTUAL_LAUNCHER_ID;
+            if (id === "./rsc/index.js") {
+              return { id: "./rsc/index.js", external: true };
+            }
+            return null;
+          },
+          load(id: string): string | null {
+            if (id === VIRTUAL_LAUNCHER_ID) return LAUNCHER_SOURCE;
+            return null;
+          },
+        },
+      ],
+    });
+    await bundle.write({
+      file: join(funcDir, "index.mjs"),
+      format: "esm",
+      exports: "default",
+      // @vercel/functions (and srvx) may contain dynamic import(); the
+      // launcher must stay a single index.mjs — Vercel's handler field
+      // points at that one file.
+      codeSplitting: false,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/@vercel\/functions/.test(message)) {
+      throw new Error(
+        '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).\n' +
+          message,
+      );
+    }
+    throw error;
+  } finally {
+    await bundle?.close();
+  }
+}
+
 /**
  * Reject a non-Node runtime for the vercel preset. The preset only emits a Node
  * serverless function (launcherType "Nodejs", bundled Node APIs, response
@@ -237,7 +366,8 @@ async function assemble(
 
   // 3. Bundle the Node launcher. srvx (a @rangojs/router dependency) is aliased
   //    to its resolved path; @vercel/functions resolves from the app; the RSC
-  //    server bundle stays a runtime-relative external.
+  //    server bundle stays a runtime-relative external. Rolldown (Vite 8's
+  //    bundler) is resolved through the app's vite install — #785.
   const rangoRequire = createRequire(import.meta.url);
   let srvxNodePath: string;
   try {
@@ -247,79 +377,7 @@ async function assemble(
       '[rango] preset "vercel" requires "srvx" (a dependency of @rangojs/router). Reinstall dependencies.',
     );
   }
-
-  // esbuild ships with Vite, so we never add it as a @rangojs/router dependency.
-  // It is a DIRECT dependency of Vite but only a TRANSITIVE one from the app's
-  // view, so under strict pnpm it is NOT resolvable from the app root. Resolve it
-  // through Vite's module location (Vite is a direct app dependency, and esbuild
-  // is a direct dependency of Vite). Minimal structural types avoid coupling to
-  // esbuild's type package at compile time.
-  const appRequire = createRequire(join(root, "package.json"));
-  const resolveEsbuildPath = (): string => {
-    try {
-      const viteRequire = createRequire(appRequire.resolve("vite"));
-      return viteRequire.resolve("esbuild");
-    } catch {
-      // Intentionally empty: fall through to the app/rango fallbacks below.
-    }
-    try {
-      return appRequire.resolve("esbuild");
-    } catch {
-      // Intentionally empty: last resort is @rangojs/router's own resolver.
-    }
-    return rangoRequire.resolve("esbuild");
-  };
-  let esbuildModule: EsbuildModule;
-  try {
-    esbuildModule = (await import(
-      pathToFileURL(resolveEsbuildPath()).href
-    )) as EsbuildModule;
-  } catch {
-    throw new Error(
-      '[rango] preset "vercel" requires "esbuild" to bundle the function launcher. It ships with Vite; reinstall dependencies (or add esbuild to your app dependencies).',
-    );
-  }
-  const esbuildBuild = esbuildModule.build ?? esbuildModule.default?.build;
-  if (typeof esbuildBuild !== "function") {
-    throw new Error('[rango] preset "vercel": could not load esbuild.build.');
-  }
-
-  try {
-    await esbuildBuild({
-      stdin: {
-        contents: LAUNCHER_SOURCE,
-        resolveDir: root,
-        sourcefile: "func-entry.mjs",
-        loader: "js",
-      },
-      outfile: join(funcDir, "index.mjs"),
-      bundle: true,
-      format: "esm",
-      platform: "node",
-      target: "node18",
-      alias: { "srvx/node": srvxNodePath },
-      plugins: [
-        {
-          name: "external-rsc-entry",
-          setup(b: EsbuildPluginBuild) {
-            b.onResolve({ filter: /^\.\/rsc\/index\.js$/ }, () => ({
-              path: "./rsc/index.js",
-              external: true,
-            }));
-          },
-        },
-      ],
-    });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (/@vercel\/functions/.test(message)) {
-      throw new Error(
-        '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).\n' +
-          message,
-      );
-    }
-    throw error;
-  }
+  await bundleVercelLauncher({ root, funcDir, srvxNodePath });
 
   // 3b. Mark the function as ESM. The rsc/ssr bundles are .js ESM files with no
   //     package.json in scope on the deployed function (it is isolated at