@rangojs/router 0.0.0-experimental.108 → 0.0.0-experimental.109

package/src/href-client.ts

@@ -15,6 +15,7 @@
  */
 
 import type { GetRegisteredRoutes } from "./types.js";
+import type { JsonSerialize } from "./serialize.js";
 import type { ResponseEnvelope } from "./urls.js";
 
 /**
@@ -103,29 +104,75 @@ type NameForPattern<TPattern extends string, TRoutes = GetRegisteredRoutes> = {
 }[keyof TRoutes];
 
 /**
- * Look up the response data type for a route pattern from RegisteredRoutes.
- *
- * Works by reverse-looking up the route name for the given pattern,
- * then extracting the response type from the route entry.
+ * Strip a query (`?…`) and/or hash (`#…`) suffix before matching, so a concrete
+ * URL like `/api/health?ts=1` still resolves to its route's response. Removes
+ * from the earliest of `?`/`#`: a `#` before the first `?` (the query is part of
+ * a fragment, e.g. `/health#top?x=1`) is handled, as is a `/:` that only appears
+ * inside the query (e.g. `/health?next=/:id`).
+ */
+type StripPathSuffix<T extends string> = T extends `${infer Base}?${string}`
+  ? Base extends `${infer Frag}#${string}`
+    ? Frag
+    : Base
+  : T extends `${infer Base}#${string}`
+    ? Base
+    : T;
+
+/** Extract a route entry's response payload (or `never` for RSC routes). */
+type ResponsePayloadOf<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends {
+  readonly response: infer R;
+}
+  ? Exclude<R, Response>
+  : never;
+
+/**
+ * Look up the response payload for a route, keyed by either a route pattern
+ * (`/api/products/:id`) or a concrete path (`/api/products/123`). The same type
+ * serves a pattern lookup and a typed `fetch` wrapper that forwards a concrete
+ * `Rango.Path`:
  *
- * For static routes (no params), pattern === path:
- *   PathResponse<"/api/health"> → { status: string; timestamp: number }
+ *   PathResponse<"/api/products/:id"> → Product   // by pattern
+ *   PathResponse<"/api/products/123"> → Product   // by concrete path
  *
- * For dynamic routes, use the pattern:
- *   PathResponse<"/api/products/:id"> → Product
+ * The query/hash suffix is stripped first; the stripped key is then treated as a
+ * pattern when it contains a `/:param` segment and matched exactly (precise even
+ * for nested dynamic routes), otherwise as a concrete path matched against each
+ * route's `PatternToPath` template. Because those holes are `${string}`
+ * (slash-greedy), a concrete path under a *nested* dynamic route can match several
+ * patterns and union their responses — pattern lookups do not have this
+ * looseness. RSC routes (no response) and unmatched keys resolve to `never`.
+ */
+type ResponsePayloadFor<
+  TPath extends string,
+  TRoutes = GetRegisteredRoutes,
+> = ResponsePayloadForKey<StripPathSuffix<TPath>, TRoutes>;
+
+type ResponsePayloadForKey<
+  TKey extends string,
+  TRoutes,
+> = TKey extends `${string}/:${string}`
+  ? {
+      [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TKey
+        ? ResponsePayloadOf<TRoutes, K>
+        : never;
+    }[keyof TRoutes]
+  : {
+      [K in keyof TRoutes]: TKey extends PatternToPath<RoutePattern<TRoutes, K>>
+        ? ResponsePayloadOf<TRoutes, K>
+        : never;
+    }[keyof TRoutes];
+
+/**
+ * Public response type for a route, keyed by pattern or concrete path. The
+ * payload is wrapped in `JsonSerialize` so it describes the JSON **wire** value a
+ * consumer receives from `fetch().then(r => r.json())`, not the handler's raw
+ * return type — e.g. a handler returning `{ createdAt: Date }` resolves here to
+ * `ResponseEnvelope<{ createdAt: string }>`.
  */
 export type PathResponse<
-  TPattern extends string,
+  TPath extends string,
   TRoutes = GetRegisteredRoutes,
-> = ResponseEnvelope<
-  {
-    [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern
-      ? TRoutes[K] extends { readonly response: infer R }
-        ? Exclude<R, Response>
-        : never
-      : never;
-  }[keyof TRoutes]
->;
+> = ResponseEnvelope<JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>>;
 
 /**
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
@@ -154,6 +201,76 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
         }[keyof TRoutes]
       >;
 
+// Module-scoped alias so the ambient `Rango.PathResponse` below can reference
+// the module-level `PathResponse` without the global namespace shadowing the
+// name when both are called `PathResponse`.
+type GlobalPathResponse<
+  TPattern extends string,
+  TRoutes = GetRegisteredRoutes,
+> = PathResponse<TPattern, TRoutes>;
+
+/**
+ * Ambient path types on the `Rango` namespace.
+ *
+ * These live on the same global namespace consumers already augment for
+ * `Rango.Env` / `Rango.Vars`, so they are reachable with no import wherever the
+ * router's types are in scope. They are the public, recommended surface for
+ * typing anything that wraps `href()`. `ValidPaths` / `PathResponse` stay as the
+ * internal building blocks behind them.
+ */
+declare global {
+  namespace Rango {
+    /**
+     * Union of every valid route path accepted by `href()`.
+     *
+     * Type a wrapper's path parameter as `Rango.Path` so it shares `href()`'s
+     * compile-time validation against the registered routes:
+     *
+     * ```ts
+     * import { href } from "@rangojs/router/client";
+     *
+     * export const appHref = (path: Rango.Path) => href(path);
+     * ```
+     *
+     * Resolves from `Rango.RegisteredRoutes` when augmented, otherwise the
+     * auto-generated `Rango.GeneratedRouteMap`, otherwise a permissive
+     * `/${string}` fallback.
+     */
+    type Path<TRoutes = GetRegisteredRoutes> = ValidPaths<TRoutes>;
+
+    /**
+     * Response payload for a route, looked up from the global route map by
+     * either a route pattern (`/api/products/:id`) or a concrete path
+     * (`/api/products/123`). Because it accepts a concrete `Rango.Path`, it
+     * doubles as the return type of a typed `fetch` wrapper:
+     *
+     * ```ts
+     * type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+     * type Same = Rango.PathResponse<"/api/products/42">;     // by concrete path
+     *
+     * const get = async <T extends Rango.Path>(
+     *   path: T,
+     * ): Promise<Rango.PathResponse<T>> =>
+     *   fetch(href(path)).then((r) => r.json());
+     * ```
+     *
+     * The payload is the JSON **wire** shape (via `Rango.JsonSerialize`), not the
+     * handler's raw return — a handler returning `{ createdAt: Date }` resolves
+     * here to `ResponseEnvelope<{ createdAt: string }>`, matching what
+     * `fetch().then(r => r.json())` actually yields.
+     *
+     * Only resolves once `Rango.RegisteredRoutes` carries response metadata (the
+     * generated map has paths and search but no payloads). Pass an explicit route
+     * map as the second argument to look up against a non-global map (rarely
+     * needed in app code).
+     */
+    type PathResponse<
+      TPath extends string,
+      TRoutes = GetRegisteredRoutes,
+    > = GlobalPathResponse<TPath, TRoutes>;
+  }
+}
+
 /**
  * Type-safe href function for client-side use
  *

package/src/index.rsc.ts

@@ -221,8 +221,8 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.js";
+// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
+// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
 
 // Telemetry sink
 export { createConsoleSink } from "./router/telemetry.js";

package/src/index.ts

@@ -303,8 +303,8 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.js";
+// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
+// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
 
 // Telemetry types only — the createConsoleSink/createOTelSink values are
 // server-only and live in index.rsc.ts (the `react-server` condition of the

package/src/serialize.ts

@@ -0,0 +1,243 @@
+/**
+ * Wire-type serialization transforms.
+ *
+ * The type a handler or loader returns on the server is frequently NOT the type
+ * a client receives after serialization. These transforms model that boundary so
+ * consumer-facing types (e.g. `Rango.PathResponse`) describe the wire value, not
+ * the source value.
+ *
+ * Two serializers, two transforms — they are intentionally NOT interchangeable:
+ *
+ * - `JsonSerialize<T>` models plain `JSON.stringify` (`path.json()` /
+ *   `fetch().then(r => r.json())`). Lossy: `Date -> string`, `undefined` /
+ *   functions / symbols dropped, `Map`/`Set` -> `{}`. `bigint` *throws* (no wire
+ *   value), so it collapses the whole result to `never`. Honors `toJSON()`.
+ * - `FlightSerialize<T>` models React RSC Flight (loaders, RSC props, cache).
+ *   High fidelity: `Date`/`Map`/`Set`/`bigint`/typed arrays/`Promise` are
+ *   preserved; ordinary functions and non-global symbols do not cross.
+ *
+ * ## Overriding (full-transform replacement)
+ *
+ * Because `Rango.JsonSerialize` / `Rango.FlightSerialize` are type *aliases*, TS
+ * cannot let you redefine them directly (aliases don't merge). Instead each alias
+ * consults a generic override slot — augment it with a single member that is your
+ * complete transform. Delegate to the built-in for the cases you don't change:
+ *
+ * ```ts
+ * declare global {
+ *   namespace Rango {
+ *     interface FlightSerializeOverride<T> {
+ *       app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+ *     }
+ *   }
+ * }
+ * // now Rango.FlightSerialize<Money> is number; everything else is the built-in.
+ * ```
+ *
+ * Provide exactly one member: the slot is read as `Override<T>[keyof Override<T>]`,
+ * so multiple members union (and conflict). The built-in recurses through the
+ * override-aware alias, so an override applies at every nesting level.
+ */
+
+import type { ReactNode } from "react";
+
+type JsonPrimitive = string | number | boolean | null;
+
+type AnyFunction = (...args: never[]) => unknown;
+
+// --- JSON ---------------------------------------------------------------------
+
+/**
+ * Internal marker for a value that makes `JSON.stringify` throw (`bigint`, or a
+ * `toJSON()` returning one). Distinct from `never`, which means "omitted":
+ * `undefined`/function/symbol-valued keys are dropped, and such array slots
+ * become `null`. A throwing value has no valid JSON wire form, so it propagates
+ * up through every container and is excluded at the public boundary (`bigint`
+ * alone -> `never`; `{ id: bigint }` -> `never`).
+ */
+declare const JSON_THROWS: unique symbol;
+type JsonThrows = typeof JSON_THROWS;
+
+/** True if union `U` contains the throw marker. */
+type HasThrow<U> = [Extract<U, JsonThrows>] extends [never] ? false : true;
+
+/** Map a JSON array/tuple: propagate a throw; else omitted elements become null. */
+type JsonSerializeArray<T extends readonly unknown[]> =
+  HasThrow<{ [K in keyof T]: JsonRawResolve<T[K]> }[number]> extends true
+    ? JsonThrows
+    : {
+        [K in keyof T]: [JsonRawResolve<T[K]>] extends [never]
+          ? null
+          : JsonRawResolve<T[K]>;
+      };
+
+/** Map a JSON object: propagate a throw; else drop omitted keys. */
+type JsonSerializeObject<T> =
+  HasThrow<{ [K in keyof T]: JsonRawResolve<T[K]> }[keyof T]> extends true
+    ? JsonThrows
+    : {
+        [K in keyof T as [JsonRawResolve<T[K]>] extends [never]
+          ? never
+          : K]: JsonRawResolve<T[K]>;
+      };
+
+/**
+ * Built-in JSON rules, *raw* (may yield the throw marker). Honors `toJSON()` (so
+ * `Date -> string` and any class with `toJSON()` serialize correctly), preserves
+ * JSON primitives and literals, omits functions / symbols / `undefined`,
+ * collapses `Map`/`Set` to `{}`, and marks `bigint` as throwing. Recurses through
+ * the override-aware resolver, so registered overrides apply at every level.
+ */
+type JsonSerializeBuiltinRaw<T> = T extends {
+  toJSON(...args: never[]): infer R;
+}
+  ? JsonRawResolve<R>
+  : T extends JsonPrimitive
+    ? T
+    : T extends bigint
+      ? JsonThrows
+      : T extends AnyFunction
+        ? never
+        : T extends symbol
+          ? never
+          : T extends undefined
+            ? never
+            : T extends readonly unknown[]
+              ? JsonSerializeArray<T>
+              : T extends ReadonlyMap<unknown, unknown>
+                ? {}
+                : T extends ReadonlySet<unknown>
+                  ? {}
+                  : T extends object
+                    ? JsonSerializeObject<T>
+                    : never;
+
+/** Override-aware raw JSON resolution (the recursion entry). */
+type JsonRawResolve<T> = [keyof Rango.JsonSerializeOverride<T>] extends [never]
+  ? JsonSerializeBuiltinRaw<T>
+  : Rango.JsonSerializeOverride<T>[keyof Rango.JsonSerializeOverride<T>];
+
+/**
+ * Model the result of round-tripping a value through `JSON.stringify` /
+ * `JSON.parse`. A registered `Rango.JsonSerializeOverride` replaces the transform
+ * wholesale; otherwise the built-in rules apply. Throwing values collapse to
+ * `never`.
+ */
+export type JsonSerialize<T> = Exclude<JsonRawResolve<T>, JsonThrows>;
+
+// --- Flight -------------------------------------------------------------------
+
+/**
+ * Built-in Flight rules. Mirrors React's `ReactClientValue` contract: primitives
+ * including `bigint`, `undefined`, `null`, symbols, `Date`, `ArrayBuffer` and
+ * typed-array views, `Map`, `Set`, `FormData`, `Blob`, `Promise`,
+ * `ReadableStream`, and (async) iterables are preserved; ordinary functions
+ * resolve to `never`. JSX (`ReactNode`, and the async-node union
+ * `ReactNode | Promise<ReactNode>`) is preserved as-is via a non-distributive
+ * leaf, so handle/loader returns that carry JSX round-trip unchanged. Recurses
+ * through the override-aware `FlightSerialize`.
+ *
+ * The source of truth is React's own contract, which is intentionally NOT
+ * semver-stable across RSC framework APIs — this tracks the React version Rango
+ * pins. See:
+ * https://react.dev/reference/rsc/use-client#serializable-types-returned-by-server-components
+ *
+ * Type-level limitations (not detectable structurally, so not modeled): class
+ * instances and null-prototype objects are rejected by React at runtime but pass
+ * here as their structural shape; non-global symbols are rejected at runtime but
+ * `symbol` is preserved here; Server Functions would need an override to be
+ * distinguished from ordinary functions (which resolve to `never`).
+ */
+type FlightSerializeBuiltinRaw<T> = [T] extends [ReactNode | Promise<ReactNode>]
+  ? T
+  : T extends string | number | boolean | bigint | symbol | null | undefined
+    ? T
+    : T extends AnyFunction
+      ? never
+      : T extends Date
+        ? Date
+        : T extends ArrayBuffer
+          ? ArrayBuffer
+          : T extends ArrayBufferView
+            ? T
+            : T extends FormData
+              ? FormData
+              : T extends Blob
+                ? Blob
+                : T extends Map<infer K, infer V>
+                  ? Map<FlightSerialize<K>, FlightSerialize<V>>
+                  : T extends Set<infer V>
+                    ? Set<FlightSerialize<V>>
+                    : T extends Promise<infer V>
+                      ? Promise<FlightSerialize<V>>
+                      : T extends ReadableStream<infer V>
+                        ? ReadableStream<FlightSerialize<V>>
+                        : T extends readonly unknown[]
+                          ? { [K in keyof T]: FlightSerialize<T[K]> }
+                          : T extends AsyncIterable<infer V>
+                            ? AsyncIterable<FlightSerialize<V>>
+                            : T extends Iterable<infer V>
+                              ? Iterable<FlightSerialize<V>>
+                              : T extends object
+                                ? { [K in keyof T]: FlightSerialize<T[K]> }
+                                : never;
+
+/**
+ * Model React RSC Flight serialization. A registered `Rango.FlightSerializeOverride`
+ * replaces the transform wholesale; otherwise the built-in rules apply.
+ */
+export type FlightSerialize<T> = [
+  keyof Rango.FlightSerializeOverride<T>,
+] extends [never]
+  ? FlightSerializeBuiltinRaw<T>
+  : Rango.FlightSerializeOverride<T>[keyof Rango.FlightSerializeOverride<T>];
+
+// Module-scoped aliases so the ambient `Rango.*` members below can reference the
+// module-level transforms without the global namespace shadowing the names.
+type GlobalJsonSerialize<T> = JsonSerialize<T>;
+type GlobalJsonSerializeBuiltin<T> = JsonSerializeBuiltinRaw<T>;
+type GlobalFlightSerialize<T> = FlightSerialize<T>;
+type GlobalFlightSerializeBuiltin<T> = FlightSerializeBuiltinRaw<T>;
+
+/**
+ * Ambient serialization transforms and their override slots on the `Rango`
+ * namespace. Available with no import wherever the router's types are in scope,
+ * alongside `Rango.Path` / `Rango.PathResponse`.
+ *
+ * `Rango.JsonSerialize` is what `Rango.PathResponse` applies; `Rango.FlightSerialize`
+ * is exposed for RSC/loader/cache wire types and must NOT be used for `path.json()`.
+ * `Rango.JsonSerializeBuiltin` / `Rango.FlightSerializeBuiltin` are the defaults,
+ * exported so an override can delegate to them.
+ */
+declare global {
+  namespace Rango {
+    /**
+     * Full-transform override slot for `Rango.JsonSerialize`. Empty by default;
+     * augment with one member that is your complete transform (delegate to
+     * `Rango.JsonSerializeBuiltin<T>` for the cases you don't change).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface JsonSerializeOverride<T> {}
+
+    /**
+     * Full-transform override slot for `Rango.FlightSerialize`. Empty by default;
+     * augment with one member that is your complete transform (delegate to
+     * `Rango.FlightSerializeBuiltin<T>` for the cases you don't change).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface FlightSerializeOverride<T> {}
+
+    /** Wire type after `JSON.stringify` (`path.json()` / `fetch().json()`). */
+    type JsonSerialize<T> = GlobalJsonSerialize<T>;
+    /**
+     * Built-in `JsonSerialize` rules, for an override to delegate to. Raw: a
+     * `bigint`-bearing type yields the internal throw marker here, which
+     * `Rango.JsonSerialize` excludes to `never` at the boundary.
+     */
+    type JsonSerializeBuiltin<T> = GlobalJsonSerializeBuiltin<T>;
+    /** Wire type after RSC Flight serialization (loaders / RSC props / cache). */
+    type FlightSerialize<T> = GlobalFlightSerialize<T>;
+    /** Built-in `FlightSerialize` rules, for an override to delegate to. */
+    type FlightSerializeBuiltin<T> = GlobalFlightSerializeBuiltin<T>;
+  }
+}

package/src/urls/type-extraction.ts

@@ -1,4 +1,5 @@
 import type { ExtractParams } from "../types.js";
+import type { JsonSerialize } from "../serialize.js";
 import type {
   TypedRouteItem,
   TypedIncludeItem,
@@ -362,11 +363,15 @@ export type ResponseEnvelope<T> =
  * type HealthData = RouteResponse<typeof apiPatterns, "health">;
  * // ResponseEnvelope<{ status: string; timestamp: number }>
  * ```
+ *
+ * The payload is the JSON wire shape (via `Rango.JsonSerialize`), matching
+ * `Rango.PathResponse` and what `fetch().then(r => r.json())` actually yields —
+ * e.g. a `Date` field resolves as `string`.
  */
 export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
   readonly _responses?: infer R;
 }
   ? TName extends keyof R
-    ? ResponseEnvelope<Exclude<R[TName], Response>>
+    ? ResponseEnvelope<JsonSerialize<Exclude<R[TName], Response>>>
     : never
   : never;

package/src/use-loader.tsx

@@ -501,7 +501,7 @@ function useLoaderInternal<T>(
 export function useLoader<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
-): UseLoaderResult<T> {
+): UseLoaderResult<Rango.FlightSerialize<T>> {
   const result = useLoaderInternal(loader, options);
 
   // Strict mode: throw if data is not in context
@@ -513,7 +513,7 @@ export function useLoader<T>(
     );
   }
 
-  return result as UseLoaderResult<T>;
+  return result as UseLoaderResult<Rango.FlightSerialize<T>>;
 }
 
 /**
@@ -565,6 +565,8 @@ export function useLoader<T>(
 export function useFetchLoader<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
-): UseFetchLoaderResult<T> {
-  return useLoaderInternal(loader, options);
+): UseFetchLoaderResult<Rango.FlightSerialize<T>> {
+  return useLoaderInternal(loader, options) as UseFetchLoaderResult<
+    Rango.FlightSerialize<T>
+  >;
 }

package/src/vite/discovery/state.ts

@@ -46,10 +46,10 @@ export interface DiscoveryState {
   isBuildMode: boolean;
   userResolveAlias: any;
   /**
-   * Data-only slice of the user's resolved config (resolve.*, define, esbuild)
-   * mirrored into the discovery temp server so it resolves and transforms
-   * modules the same way the real environment does. See
-   * `utils/forward-user-plugins.ts`.
+   * Data-only slice of the user's resolved config (resolve.* incl. native
+   * tsconfigPaths, define, oxc) mirrored into the discovery temp server so it
+   * resolves and transforms modules the same way the real environment does.
+   * See `utils/forward-user-plugins.ts`.
    */
   userRunnerConfig:
     | import("../utils/forward-user-plugins.js").ForwardedRunnerConfig

package/src/vite/router-discovery.ts

@@ -141,9 +141,8 @@ async function createTempRscServer(
   const resolveConfig = runnerConfig?.resolve ?? {
     alias: state.userResolveAlias,
   };
-  const esbuildConfig = runnerConfig?.esbuild ?? {
-    jsx: "automatic",
-    jsxImportSource: "react",
+  const oxcConfig = runnerConfig?.oxc ?? {
+    jsx: { runtime: "automatic", importSource: "react" },
   };
   return createViteServer({
     root: state.projectRoot,
@@ -153,7 +152,7 @@ async function createTempRscServer(
     logLevel: "silent",
     resolve: resolveConfig,
     ...(runnerConfig?.define ? { define: runnerConfig.define } : {}),
-    esbuild: esbuildConfig as any,
+    oxc: oxcConfig as any,
     ...(options.cacheDir && { cacheDir: options.cacheDir }),
     plugins: [
       rsc({
@@ -330,12 +329,14 @@ export function createRouterDiscoveryPlugin(
       viteMode = config.mode;
       // Capture user's resolve aliases for the temp server
       s.userResolveAlias = config.resolve.alias;
-      // Capture the data-only resolution config (resolve.*, define, esbuild)
-      // and the user's resolution plugins (resolveId/load) so the discovery
-      // temp server resolves modules the same way the real environment does.
-      // Without this, third-party resolvers (e.g. vite-tsconfig-paths) are
-      // absent during discovery/prerender/static rendering even though they
-      // apply at request time. See utils/forward-user-plugins.ts.
+      // Capture the data-only resolution config (resolve.*, define, oxc) and
+      // the user's resolution plugins (resolveId/load) so the discovery temp
+      // server resolves modules the same way the real environment does.
+      // Without this, both flavors of user resolution are absent during
+      // discovery/prerender/static rendering even though they apply at request
+      // time: third-party resolvers (e.g. vite-tsconfig-paths, forwarded as
+      // plugins) and Vite 8's native resolve.tsconfigPaths (forwarded in the
+      // data slice). See utils/forward-user-plugins.ts.
       s.userRunnerConfig = pickForwardedRunnerConfig(config);
       s.userResolvePlugins = selectForwardableResolvePlugins(
         config.plugins as any,

package/src/vite/utils/forward-user-plugins.ts

@@ -4,14 +4,20 @@
  * The discovery temp server (createTempRscServer) runs the user's handler
  * graph through a throwaway Node Vite server built with `configFile: false`.
  * Without help, that server only sees a fixed Rango-owned plugin set, so any
- * user resolution provided by third-party plugins (e.g. vite-tsconfig-paths)
- * is absent during discovery, prerender, and static handler rendering — even
- * though it applies at request time.
+ * user resolution is absent during discovery, prerender, and static handler
+ * rendering — even though it applies at request time. Two flavors of user
+ * resolution must be carried across:
+ *
+ * - Third-party resolveId plugins (e.g. vite-tsconfig-paths) — forwarded as
+ *   plugin instances, see selectForwardableResolvePlugins.
+ * - Native config-driven resolution, including Vite 8's built-in
+ *   `resolve.tsconfigPaths` (which supersedes vite-tsconfig-paths) — forwarded
+ *   as the data slice, see pickForwardedRunnerConfig.
  *
  * These helpers extract the resolution-relevant slice of the user's resolved
- * config (resolve.*, define, esbuild) and forward the user's resolution
- * plugins into the temp server so discovery resolves modules the same way the
- * real environment does.
+ * config (resolve.*, define, oxc) and forward the user's resolution plugins
+ * into the temp server so discovery resolves modules the same way the real
+ * environment does.
  */
 
 import type { Plugin, ResolvedConfig, UserConfig } from "vite";
@@ -120,22 +126,31 @@ export function selectForwardableResolvePlugins(
 /**
  * The resolution-relevant slice of the user's resolved config that is plain
  * data (no plugin re-execution): everything under `resolve` that influences
- * how specifiers map to files, plus `define` and `esbuild` so transforms and
+ * how specifiers map to files, plus `define` and `oxc` so transforms and
  * compile-time constants match request time.
  */
 export interface ForwardedRunnerConfig {
   resolve: UserConfig["resolve"];
   define: UserConfig["define"];
-  esbuild: UserConfig["esbuild"];
+  oxc: UserConfig["oxc"];
 }
 
 /**
  * Extract the data-only config slice to mirror into the discovery temp server.
  * `alias` is included here so callers no longer need to thread it separately.
  *
- * `esbuild` keeps the user's options but always pins the RSC-required JSX
- * runtime, since the temp server compiles the handler graph as React server
- * components regardless of the user's app-level JSX config.
+ * `tsconfigPaths` is forwarded so Vite 8's native tsconfig `paths` resolution
+ * (a top-level `resolve` flag, off by default) reaches the temp server. The
+ * server is created with `configFile: false` and an explicit, allowlisted
+ * resolve slice, so a flag that is not copied here is simply absent during
+ * discovery — which would make path-aliased imports fail at prerender/static
+ * time the same way unforwarded resolveId plugins did (issue #500).
+ *
+ * `oxc` keeps the user's options but always pins the RSC-required JSX runtime
+ * (automatic, react), since the temp server compiles the handler graph as
+ * React server components regardless of the user's app-level JSX config. Vite 8
+ * replaced the deprecated `esbuild` transform option with `oxc`, so we read and
+ * forward `oxc` exclusively — no `esbuild` field is touched.
  */
 export function pickForwardedRunnerConfig(
   config: ResolvedConfig,
@@ -149,16 +164,30 @@ export function pickForwardedRunnerConfig(
   if (r.extensions !== undefined) resolve.extensions = r.extensions;
   if (r.preserveSymlinks !== undefined)
     resolve.preserveSymlinks = r.preserveSymlinks;
+  if (r.tsconfigPaths !== undefined) resolve.tsconfigPaths = r.tsconfigPaths;
 
-  const userEsbuild = config.esbuild;
-  const esbuild: UserConfig["esbuild"] =
-    userEsbuild && typeof userEsbuild === "object"
-      ? { ...userEsbuild, jsx: "automatic", jsxImportSource: "react" }
-      : { jsx: "automatic", jsxImportSource: "react" };
+  // Pin the RSC JSX runtime on top of the user's oxc options. The user's
+  // jsx sub-options (e.g. `development`) are preserved when present; only
+  // `runtime`/`importSource` are forced to the values the RSC compile needs.
+  const userOxc = config.oxc;
+  const userJsx =
+    userOxc &&
+    typeof userOxc === "object" &&
+    typeof userOxc.jsx === "object" &&
+    userOxc.jsx !== null
+      ? userOxc.jsx
+      : {};
+  const oxc: UserConfig["oxc"] =
+    userOxc && typeof userOxc === "object"
+      ? {
+          ...userOxc,
+          jsx: { ...userJsx, runtime: "automatic", importSource: "react" },
+        }
+      : { jsx: { runtime: "automatic", importSource: "react" } };
 
   return {
     resolve,
     define: config.define,
-    esbuild,
+    oxc,
   };
 }