@rangojs/router 0.0.0-experimental.0b82333f

package/src/use-loader.tsx

@@ -0,0 +1,354 @@
+"use client";
+
+import { useCallback, useContext, useEffect, useRef, useState } from "react";
+import { OutletContext, type OutletContextValue } from "./outlet-context.js";
+import type { LoaderDefinition, LoadOptions } from "./types.js";
+
+/**
+ * Payload returned by loader RSC requests
+ */
+interface LoaderRscPayload<T = unknown> {
+  loaderResult: T;
+  loaderError?: { message: string; name: string };
+}
+
+/**
+ * Load function type for fetching loader data from the client
+ */
+export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
+
+/**
+ * Result type for useLoader hook (strict - data is required)
+ */
+export interface UseLoaderResult<T> {
+  /** The loaded data - guaranteed to exist when loader is registered on route */
+  data: T;
+  /** True while a load() is in progress */
+  isLoading: boolean;
+  /** Error from the most recent load attempt, null if successful */
+  error: Error | null;
+  /** Function to trigger a fetch (only works if loader is fetchable) */
+  load: LoadFunction<T>;
+  /** Alias for load */
+  refetch: LoadFunction<T>;
+}
+
+/**
+ * Result type for useFetchLoader hook (flexible - data is optional)
+ */
+export interface UseFetchLoaderResult<T> {
+  /** The loaded data - may be undefined if not yet fetched or not in context */
+  data: T | undefined;
+  /** True while a load() is in progress */
+  isLoading: boolean;
+  /** Error from the most recent load attempt, null if successful */
+  error: Error | null;
+  /** Function to trigger a fetch (only works if loader is fetchable) */
+  load: LoadFunction<T>;
+  /** Alias for load */
+  refetch: LoadFunction<T>;
+}
+
+/**
+ * Options for useLoader hook
+ */
+export interface UseLoaderOptions {
+  /**
+   * If true (default), errors from load() will be thrown to the nearest error boundary.
+   * If false, errors are only captured in the `error` state.
+   * @default true
+   */
+  throwOnError?: boolean;
+}
+
+/**
+ * Internal hook implementation shared by useLoader and useFetchLoader
+ */
+function useLoaderInternal<T>(
+  loader: LoaderDefinition<T>,
+  options?: UseLoaderOptions,
+): UseFetchLoaderResult<T> {
+  const context = useContext(OutletContext);
+
+  // Get data from context (SSR/navigation)
+  const getContextData = useCallback((): T | undefined => {
+    let current: OutletContextValue | null | undefined = context;
+    while (current) {
+      if (current.loaderData && loader.$$id in current.loaderData) {
+        return current.loaderData[loader.$$id] as T;
+      }
+      current = current.parent;
+    }
+    return undefined;
+  }, [context, loader.$$id]);
+
+  const contextData = getContextData();
+
+  // Local state for fetched data (from load() calls)
+  const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const requestIdRef = useRef(0);
+
+  // Track context data changes to reset fetched data on navigation
+  const prevContextDataRef = useRef(contextData);
+  useEffect(() => {
+    if (prevContextDataRef.current !== contextData) {
+      // Navigation happened, clear fetched data so context takes precedence
+      setFetchedData(undefined);
+      setError(null);
+      prevContextDataRef.current = contextData;
+    }
+  }, [contextData]);
+
+  // Data priority: fetched data (if any) > context data
+  const data = fetchedData ?? contextData;
+
+  const throwOnError = options?.throwOnError ?? true;
+
+  // Refs for values used inside load() that should NOT cause callback identity
+  // churn. loader.$$id can change if a reusable component receives a different
+  // loader without remounting; data changes on every navigation. Refs keep the
+  // callback stable while always reading the latest values.
+  const loaderIdRef = useRef(loader.$$id);
+  loaderIdRef.current = loader.$$id;
+  const dataRef = useRef(data);
+  dataRef.current = data;
+
+  // Load function for fetching data via the ?_rsc_loader endpoint.
+  // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
+  const load = useCallback(
+    async (loadOptions?: LoadOptions): Promise<T> => {
+      const requestId = ++requestIdRef.current;
+      const loaderId = loaderIdRef.current;
+      // Verify the loader has $$id
+      if (!loaderId) {
+        throw new Error(
+          `Loader is missing $$id. Make sure the exposeLoaderId Vite plugin is enabled.`,
+        );
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const url = new URL(window.location.href);
+        url.searchParams.set("_rsc_loader", loaderId);
+
+        const method = loadOptions?.method ?? "GET";
+        const isBodyMethod = method !== "GET";
+
+        let fetchOptions: RequestInit;
+
+        if (isBodyMethod) {
+          const bodyValue =
+            "body" in (loadOptions ?? {})
+              ? (loadOptions as any).body
+              : undefined;
+          const hasParams =
+            loadOptions?.params && Object.keys(loadOptions.params).length > 0;
+
+          if (bodyValue instanceof FormData) {
+            // FormData body — send as multipart/form-data (preserves File objects).
+            // Params are appended as a JSON string in a special field.
+            if (hasParams) {
+              bodyValue.set(
+                "_rsc_loader_params",
+                JSON.stringify(loadOptions!.params),
+              );
+            }
+            fetchOptions = {
+              method,
+              headers: { Accept: "text/x-component" },
+              body: bodyValue,
+            };
+          } else {
+            // JSON body — send params and body as JSON
+            const bodyPayload: {
+              params?: Record<string, string>;
+              body?: unknown;
+            } = {};
+            if (hasParams) {
+              bodyPayload.params = loadOptions!.params;
+            }
+            if (bodyValue !== undefined) {
+              bodyPayload.body = bodyValue;
+            }
+
+            fetchOptions = {
+              method,
+              headers: {
+                Accept: "text/x-component",
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify(bodyPayload),
+            };
+          }
+        } else {
+          // GET - send params in query string
+          if (
+            loadOptions?.params &&
+            Object.keys(loadOptions.params).length > 0
+          ) {
+            url.searchParams.set(
+              "_rsc_loader_params",
+              JSON.stringify(loadOptions.params),
+            );
+          }
+
+          fetchOptions = {
+            method: "GET",
+            headers: {
+              Accept: "text/x-component",
+            },
+          };
+        }
+
+        const response = fetch(url.toString(), fetchOptions);
+
+        const { createFromFetch } = await import("./deps/browser.js");
+        const payload = await createFromFetch<LoaderRscPayload<T>>(response);
+
+        if (payload.loaderError) {
+          throw new Error(payload.loaderError.message);
+        }
+
+        const result = payload.loaderResult;
+        if (requestId === requestIdRef.current) {
+          setFetchedData(result);
+        }
+        return result;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        if (requestId === requestIdRef.current) {
+          setError(err);
+        }
+        if (throwOnError) {
+          throw err;
+        }
+        // When throwOnError is false, return the latest data snapshot (previous
+        // successful value or undefined). Caller should check error state.
+        return dataRef.current as T;
+      } finally {
+        if (requestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [throwOnError],
+  );
+
+  // Throw during render if there's an error and throwOnError is true
+  // This allows ErrorBoundaries to catch async errors from load()
+  if (error && throwOnError) {
+    throw error;
+  }
+
+  return {
+    data,
+    isLoading,
+    error,
+    load,
+    refetch: load,
+  };
+}
+
+/**
+ * Hook to access loader data from route context (strict version)
+ *
+ * Use this when the loader is registered on the route via `loader()`.
+ * The data is guaranteed to exist - throws an error if not found.
+ *
+ * For on-demand fetching or when loader might not be in context,
+ * use `useFetchLoader` instead.
+ *
+ * @param loader - The loader definition (must be registered on route)
+ * @param options - Optional configuration
+ * @returns Object with data (guaranteed), isLoading, error, load, and refetch
+ * @throws Error if loader data is not found in context
+ *
+ * @example Basic usage - accessing route loader data
+ * ```tsx
+ * "use client";
+ * import { useLoader } from "rsc-router/client";
+ * import { CartLoader } from "../loaders/cart";
+ *
+ * // In route definition: loader(CartLoader)
+ *
+ * export function CartIcon() {
+ *   const { data } = useLoader(CartLoader);
+ *   // data is guaranteed to be CartData, not CartData | undefined
+ *   return <span>Cart ({data.items.length})</span>;
+ * }
+ * ```
+ */
+export function useLoader<T>(
+  loader: LoaderDefinition<T>,
+  options?: UseLoaderOptions,
+): UseLoaderResult<T> {
+  const result = useLoaderInternal(loader, options);
+
+  // Strict mode: throw if data is not in context
+  if (result.data === undefined) {
+    throw new Error(
+      `useLoader: Loader "${loader.$$id}" data not found in context. ` +
+        `Make sure the loader is registered on the route with loader(). ` +
+        `If you need on-demand fetching, use useFetchLoader() instead.`,
+    );
+  }
+
+  return result as UseLoaderResult<T>;
+}
+
+/**
+ * Hook to access loader data with optional fetching (flexible version)
+ *
+ * Use this when:
+ * - The loader might not be registered on the route
+ * - You want to fetch data on-demand from the client
+ * - You're building a reusable component that doesn't assume route context
+ *
+ * If the loader IS registered on the route, it will still get the initial
+ * data from context - you just have to handle the `undefined` case in types.
+ *
+ * @param loader - The loader definition
+ * @param options - Optional configuration
+ * @returns Object with data (may be undefined), isLoading, error, load, and refetch
+ *
+ * @example On-demand fetching
+ * ```tsx
+ * "use client";
+ * import { useFetchLoader } from "rsc-router/client";
+ * import { SearchLoader } from "../loaders/search";
+ *
+ * export function SearchResults() {
+ *   const { data, load, isLoading } = useFetchLoader(SearchLoader);
+ *
+ *   const handleSearch = async (query: string) => {
+ *     await load({ params: { query } });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => handleSearch("test")}>Search</button>
+ *       {isLoading && <span>Loading...</span>}
+ *       {data?.results.map(r => <div key={r.id}>{r.name}</div>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With route context (hybrid usage)
+ * ```tsx
+ * // Loader registered on route: loader(UserLoader)
+ * // useFetchLoader still works - gets initial data from context
+ * const { data, load } = useFetchLoader(UserLoader);
+ * // data is UserData | undefined (even though it will have initial value)
+ * ```
+ */
+export function useFetchLoader<T>(
+  loader: LoaderDefinition<T>,
+  options?: UseLoaderOptions,
+): UseFetchLoaderResult<T> {
+  return useLoaderInternal(loader, options);
+}

package/src/vite/discovery/bundle-postprocess.ts

@@ -0,0 +1,184 @@
+/**
+ * Bundle Post-Processing
+ *
+ * Handles handler code eviction from prerender/static chunks and
+ * injection of collected prerender/static data into the RSC entry bundle.
+ */
+
+import { resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { evictHandlerCode } from "../utils/bundle-analysis.js";
+import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
+import type { DiscoveryState } from "./state.js";
+
+/**
+ * Post-process the RSC bundle: evict handler code and inject
+ * prerender/static data as importable asset modules.
+ */
+export function postprocessBundle(state: DiscoveryState): void {
+  const hasPrerenderData =
+    state.prerenderManifestEntries &&
+    Object.keys(state.prerenderManifestEntries).length > 0;
+  const hasStaticData =
+    state.staticManifestEntries &&
+    Object.keys(state.staticManifestEntries).length > 0;
+  if (!hasPrerenderData && !hasStaticData) return;
+
+  // Find RSC entry (recorded in generateBundle, fallback to dist/rsc/index.js)
+  const rscEntryPath = resolve(
+    state.projectRoot,
+    "dist/rsc",
+    state.rscEntryFileName ?? "index.js",
+  );
+
+  // 1. Evict handler code from __prerender-handlers and __static-handlers chunks.
+  // handlerChunkInfo/staticHandlerChunkInfo are populated by generateBundle
+  // after the production RSC build. In Vite 6 multi-environment builds, the
+  // RSC build runs twice (analysis + production). Chunk info is only available
+  // after the production pass, so we run eviction whenever it becomes available.
+  const evictionTargets: Array<{
+    info: typeof state.handlerChunkInfo;
+    fnName: string;
+    brand: string;
+    label: string;
+  }> = [
+    {
+      info: state.handlerChunkInfo,
+      fnName: "Prerender",
+      brand: "prerenderHandler",
+      label: "handler code from RSC bundle",
+    },
+    {
+      info: state.staticHandlerChunkInfo,
+      fnName: "Static",
+      brand: "staticHandler",
+      label: "static handler code",
+    },
+  ];
+
+  for (const target of evictionTargets) {
+    if (!target.info) continue;
+    const chunkPath = resolve(
+      state.projectRoot,
+      "dist/rsc",
+      target.info.fileName,
+    );
+    try {
+      const code = readFileSync(chunkPath, "utf-8");
+      const result = evictHandlerCode(
+        code,
+        target.info.exports,
+        target.fnName,
+        target.brand,
+      );
+      if (result) {
+        writeFileSync(chunkPath, result.code);
+        const savedKB = (result.savedBytes / 1024).toFixed(1);
+        console.log(
+          `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${target.info.fileName}`,
+        );
+      }
+    } catch (replaceErr: any) {
+      console.warn(
+        `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
+      );
+    }
+  }
+  state.handlerChunkInfo = null;
+  state.staticHandlerChunkInfo = null;
+
+  // 2. Write prerender data as separate importable asset modules
+  // and inject a lazy manifest loader into the RSC entry.
+  if (hasPrerenderData && existsSync(rscEntryPath)) {
+    const rscCode = readFileSync(rscEntryPath, "utf-8");
+    // Check for the specific injection marker to avoid double-injection.
+    if (!rscCode.includes("__prerender-manifest.js")) {
+      try {
+        let totalBytes = copyStagedBuildAssets(
+          state.projectRoot,
+          Object.values(state.prerenderManifestEntries!),
+        );
+
+        const manifestMap: Record<string, string> = {};
+        for (const [key, assetFileName] of Object.entries(
+          state.prerenderManifestEntries!,
+        )) {
+          manifestMap[key] = `./assets/${assetFileName}`;
+        }
+
+        const manifestCode = [
+          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `export function loadPrerenderAsset(s){return import(s)}`,
+          `export default m;`,
+          "",
+        ].join("\n");
+        const manifestPath = resolve(
+          state.projectRoot,
+          "dist/rsc/__prerender-manifest.js",
+        );
+        writeFileSync(manifestPath, manifestCode);
+        totalBytes += Buffer.byteLength(manifestCode);
+
+        const injection = `globalThis.__loadPrerenderManifestModule = () => import("./__prerender-manifest.js");\n`;
+        writeFileSync(rscEntryPath, injection + rscCode);
+
+        const totalKB = (totalBytes / 1024).toFixed(1);
+        console.log(
+          `[rsc-router] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
+        );
+      } catch (err: any) {
+        throw new Error(
+          `[rsc-router] Failed to write prerender assets: ${err.message}`,
+        );
+      }
+    }
+  }
+
+  // 3. Write static handler data as separate importable asset modules
+  // and inject a __STATIC_MANIFEST import into the RSC entry.
+  if (hasStaticData && existsSync(rscEntryPath)) {
+    const rscCode = readFileSync(rscEntryPath, "utf-8");
+    if (!rscCode.includes("__STATIC_MANIFEST")) {
+      try {
+        const manifestEntries: string[] = [];
+        let totalBytes = copyStagedBuildAssets(
+          state.projectRoot,
+          Object.values(state.staticManifestEntries!),
+        );
+
+        for (const [handlerId, assetFileName] of Object.entries(
+          state.staticManifestEntries!,
+        )) {
+          manifestEntries.push(
+            `${JSON.stringify(handlerId)}:()=>import("./assets/${assetFileName}")`,
+          );
+        }
+
+        // Set the global inside the manifest module so it is assigned
+        // during module evaluation (before dependent modules like
+        // segment-resolution.ts run their top-level initializers).
+        const manifestCode = `const m={${manifestEntries.join(",")}};globalThis.__STATIC_MANIFEST=m;export default m;\n`;
+        const manifestPath = resolve(
+          state.projectRoot,
+          "dist/rsc/__static-manifest.js",
+        );
+        writeFileSync(manifestPath, manifestCode);
+        totalBytes += Buffer.byteLength(manifestCode);
+
+        // The import ensures the manifest module is evaluated early.
+        // The global is already set inside the module itself.
+        const injection = `import "./__static-manifest.js";\n`;
+        writeFileSync(rscEntryPath, injection + rscCode);
+
+        const totalKB = (totalBytes / 1024).toFixed(1);
+        console.log(
+          `[rsc-router] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
+        );
+      } catch (err: any) {
+        throw new Error(
+          `[rsc-router] Failed to write static assets: ${err.message}`,
+        );
+      }
+    }
+  }
+}