@ivogt/rsc-router 0.0.0-experimental.1 → 0.0.0-experimental.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivogt/rsc-router",
-  "version": "0.0.0-experimental.1",
+  "version": "0.0.0-experimental.11",
   "type": "module",
   "description": "Type-safe RSC router with partial rendering support",
   "author": "Ivo Todorov",
@@ -55,7 +55,7 @@
     },
     "./vite": {
       "types": "./src/vite/index.ts",
-      "import": "./src/vite/index.ts"
+      "import": "./dist/vite/index.js"
     },
     "./types": {
       "types": "./src/vite/version.d.ts"
@@ -89,6 +89,7 @@
   },
   "files": [
     "src",
+    "dist",
     "README.md"
   ],
   "peerDependencies": {
@@ -117,11 +118,13 @@
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
+    "esbuild": "^0.27.0",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^2.1.8"
   },
   "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external",
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
     "test:ui": "playwright test --ui",

package/src/router.ts

@@ -160,6 +160,39 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
 
+  /**
+   * Component to render when no route matches the requested URL.
+   *
+   * This is rendered within your document/app shell with a 404 status code.
+   * Use this for a custom 404 page that maintains your app's look and feel.
+   *
+   * If not provided, a default "Page not found" component is rendered.
+   *
+   * Can be a static ReactNode or a function receiving the pathname.
+   *
+   * @example
+   * ```typescript
+   * // Simple static component
+   * const router = createRSCRouter<AppEnv>({
+   *   document: AppShell,
+   *   notFound: <NotFound404 />,
+   * });
+   *
+   * // Dynamic component with pathname
+   * const router = createRSCRouter<AppEnv>({
+   *   document: AppShell,
+   *   notFound: ({ pathname }) => (
+   *     <div>
+   *       <h1>404 - Not Found</h1>
+   *       <p>No page exists at {pathname}</p>
+   *       <a href="/">Go home</a>
+   *     </div>
+   *   ),
+   * });
+   * ```
+   */
+  notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
+
   /**
    * Callback invoked when an error occurs during request handling.
    *
@@ -368,6 +401,11 @@ export interface RSCRouter<
    */
   readonly cache?: RSCRouterOptions<TEnv>["cache"];
 
+  /**
+   * Not found component to render when no route matches (for internal use by RSC handler)
+   */
+  readonly notFound?: RSCRouterOptions<TEnv>["notFound"];
+
   /**
    * App-level middleware entries (for internal use by RSC handler)
    * These wrap the entire request/response cycle
@@ -456,6 +494,7 @@ export function createRSCRouter<TEnv = any>(
     document: documentOption,
     defaultErrorBoundary,
     defaultNotFoundBoundary,
+    notFound,
     onError,
     cache,
   } = options;
@@ -3471,6 +3510,9 @@ export function createRSCRouter<TEnv = any>(
     // Expose cache configuration for RSC handler
     cache,
 
+    // Expose notFound component for RSC handler
+    notFound,
+
     // Expose global middleware for RSC handler
     middleware: globalMiddleware,
 

package/src/rsc/handler.ts

@@ -7,6 +7,7 @@
  * and progressive enhancement (no-JS form submissions).
  */
 
+import { createElement } from "react";
 import { renderSegments } from "../segment-system.js";
 import { RouteNotFoundError } from "../errors.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
@@ -291,22 +292,85 @@ export function createRSCHandler<TEnv = unknown>(
       // ============================================================================
       // REGULAR RSC RENDERING (Navigation)
       // ============================================================================
-      return handleRscRendering(request, env, url, isPartial, handleStore, nonce);
+      // Note: Must use "return await" for try/catch to catch async rejections
+      return await handleRscRendering(request, env, url, isPartial, handleStore, nonce);
     } catch (error) {
       // Check if middleware/handler returned Response
       if (error instanceof Response) {
         return error;
       }
 
-      // Return 404 for unmatched routes instead of 500
-      if (error instanceof RouteNotFoundError) {
+      // Render 404 page for unmatched routes
+      // Check both instanceof and error.name for cross-bundle compatibility
+      const isRouteNotFound =
+        error instanceof RouteNotFoundError ||
+        (error instanceof Error && error.name === "RouteNotFoundError");
+      if (isRouteNotFound) {
         callOnError(error, "routing", {
           request,
           url,
           env,
-          handledByBoundary: false,
+          handledByBoundary: true, // Handled by notFound component
+        });
+
+        // Get notFound component from router options or use default
+        const notFoundOption = router.notFound;
+        const notFoundComponent =
+          typeof notFoundOption === "function"
+            ? notFoundOption({ pathname: url.pathname })
+            : notFoundOption ?? createElement("h1", null, "Not Found");
+
+        // Create a simple segment for the 404 page
+        const notFoundSegment = {
+          id: "notFound",
+          namespace: "notFound",
+          type: "route" as const,
+          index: 0,
+          component: notFoundComponent,
+          params: {},
+        };
+
+        // Render with rootLayout to maintain app shell
+        const root = await renderSegments([notFoundSegment], {
+          rootLayout: router.rootLayout,
+        });
+
+        const payload: RscPayload = {
+          root,
+          metadata: {
+            pathname: url.pathname,
+            segments: [notFoundSegment],
+            matched: [],
+            diff: [],
+            isPartial: false,
+            handles: handleStore.stream(),
+            version,
+          },
+        };
+
+        const rscStream = renderToReadableStream(payload);
+
+        // Determine if this is an RSC request or HTML request
+        const isRscRequest =
+          (!request.headers.get("accept")?.includes("text/html") &&
+            !url.searchParams.has("__html")) ||
+          url.searchParams.has("__rsc");
+
+        if (isRscRequest) {
+          return createResponseWithMergedHeaders(rscStream, {
+            status: 404,
+            headers: { "content-type": "text/x-component;charset=utf-8" },
+          });
+        }
+
+        // Delegate to SSR for HTML response
+        const ssrModule = await loadSSRModule();
+        const htmlStream = await ssrModule.renderHTML(rscStream, { nonce });
+
+        return createResponseWithMergedHeaders(htmlStream, {
+          status: 404,
+          headers: { "content-type": "text/html;charset=utf-8" },
         });
-        return createResponseWithMergedHeaders("Not Found", { status: 404 });
       }
 
       // Report unhandled errors

package/src/server/root-layout.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import { Outlet } from "rsc-router/client";
+import { Outlet } from "../client.js";
 
 const MapRootLayout = (
   <>

package/src/vite/index.ts

@@ -12,6 +12,12 @@ import {
   getVirtualVersionContent,
   VIRTUAL_IDS,
 } from "./virtual-entries.ts";
+import {
+  getExcludeDeps,
+  getPackageAliases,
+  getPublishedPackageName,
+  isWorkspaceDevelopment,
+} from "./package-resolution.ts";
 
 // Re-export plugins
 export { exposeActionId } from "./expose-action-id.ts";
@@ -21,6 +27,33 @@ export { exposeLocationStateId } from "./expose-location-state-id.ts";
 
 // Virtual module type declarations in ./version.d.ts
 
+/**
+ * esbuild plugin to provide rsc-router:version virtual module during optimization.
+ * This is needed because esbuild runs during Vite's dependency optimization phase,
+ * before Vite's plugin system can handle virtual modules.
+ */
+const versionEsbuildPlugin = {
+  name: "rsc-router-version",
+  setup(build: any) {
+    build.onResolve({ filter: /^rsc-router:version$/ }, (args: any) => ({
+      path: args.path,
+      namespace: "rsc-router-virtual",
+    }));
+    build.onLoad({ filter: /.*/, namespace: "rsc-router-virtual" }, () => ({
+      contents: `export const VERSION = "dev";`,
+      loader: "js",
+    }));
+  },
+};
+
+/**
+ * Shared esbuild options for dependency optimization.
+ * Includes the version stub plugin for all environments.
+ */
+const sharedEsbuildOptions = {
+  plugins: [versionEsbuildPlugin],
+};
+
 /**
  * RSC plugin entry points configuration.
  * All entries use virtual modules by default. Specify a path to use a custom entry file.
@@ -399,6 +432,10 @@ export async function rscRouter(
 
   const plugins: PluginOption[] = [];
 
+  // Get package resolution info (workspace vs npm install)
+  const rscRouterAliases = getPackageAliases();
+  const excludeDeps = getExcludeDeps();
+
   // Track RSC entry path for version injection
   let rscEntryPath: string | null = null;
 
@@ -422,6 +459,15 @@ export async function rscRouter(
       config() {
         // Configure environments for cloudflare deployment
         return {
+          // Exclude rsc-router modules from optimization to prevent module duplication
+          // This ensures the same Context instance is used by both browser entry and RSC proxy modules
+          optimizeDeps: {
+            exclude: excludeDeps,
+            esbuildOptions: sharedEsbuildOptions,
+          },
+          resolve: {
+            alias: rscRouterAliases,
+          },
           environments: {
             client: {
               build: {
@@ -432,8 +478,11 @@ export async function rscRouter(
                 },
               },
               // Pre-bundle rsc-html-stream to prevent discovery during first request
+              // Exclude rsc-router modules to ensure same Context instance
               optimizeDeps: {
                 include: ["rsc-html-stream/client"],
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions,
               },
             },
             ssr: {
@@ -446,6 +495,7 @@ export async function rscRouter(
                 dedupe: ["react", "react-dom"],
               },
               // Pre-bundle SSR entry and React for proper module linking with childEnvironments
+              // Exclude rsc-router modules to ensure same Context instance
               optimizeDeps: {
                 entries: [finalEntries.ssr],
                 include: [
@@ -454,6 +504,16 @@ export async function rscRouter(
                   "react/jsx-runtime",
                   "rsc-html-stream/server",
                 ],
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions,
+              },
+            },
+            rsc: {
+              // RSC environment needs exclude list and esbuild options
+              // Exclude rsc-router modules to prevent createContext in RSC environment
+              optimizeDeps: {
+                exclude: excludeDeps,
+                esbuildOptions: sharedEsbuildOptions,
               },
             },
           },
@@ -515,6 +575,15 @@ export async function rscRouter(
           const useVirtualRSC = finalEntries.rsc === VIRTUAL_IDS.rsc;
 
           return {
+            // Exclude rsc-router modules from optimization to prevent module duplication
+            // This ensures the same Context instance is used by both browser entry and RSC proxy modules
+            optimizeDeps: {
+              exclude: excludeDeps,
+              esbuildOptions: sharedEsbuildOptions,
+            },
+            resolve: {
+              alias: rscRouterAliases,
+            },
             environments: {
               client: {
                 build: {
@@ -524,12 +593,15 @@ export async function rscRouter(
                     },
                   },
                 },
-                ...(useVirtualClient && {
-                  optimizeDeps: {
+                // Always exclude rsc-router modules, conditionally add virtual entry
+                optimizeDeps: {
+                  exclude: excludeDeps,
+                  esbuildOptions: sharedEsbuildOptions,
+                  ...(useVirtualClient && {
                     // Tell Vite to scan the virtual entry for dependencies
                     entries: [VIRTUAL_IDS.browser],
-                  },
-                }),
+                  }),
+                },
               },
               ...(useVirtualSSR && {
                 ssr: {
@@ -537,6 +609,8 @@ export async function rscRouter(
                     entries: [VIRTUAL_IDS.ssr],
                     // Pre-bundle React for SSR to ensure single instance
                     include: ["react", "react-dom/server.edge", "react/jsx-runtime"],
+                    exclude: excludeDeps,
+                    esbuildOptions: sharedEsbuildOptions,
                   },
                 },
               }),
@@ -546,6 +620,7 @@ export async function rscRouter(
                     entries: [VIRTUAL_IDS.rsc],
                     // Pre-bundle React for RSC to ensure single instance
                     include: ["react", "react/jsx-runtime"],
+                    esbuildOptions: sharedEsbuildOptions,
                   },
                 },
               }),
@@ -603,6 +678,93 @@ export async function rscRouter(
     plugins.push(createVersionInjectorPlugin(rscEntryPath));
   }
 
+  // Transform CJS vendor files to ESM for browser compatibility
+  // optimizeDeps.include doesn't work because the file is loaded after initial optimization
+  plugins.push(createCjsToEsmPlugin());
+
   return plugins;
 }
 
+/**
+ * Transform CJS vendor files from @vitejs/plugin-rsc to ESM for browser compatibility.
+ * The react-server-dom vendor files are shipped as CJS which doesn't work in browsers.
+ */
+function createCjsToEsmPlugin(): Plugin {
+  return {
+    name: "rsc-router:cjs-to-esm",
+    enforce: "pre",
+    transform(code, id) {
+      const cleanId = id.split("?")[0];
+
+      // Transform the client.browser.js entry point to re-export from CJS
+      if (
+        cleanId.includes("vendor/react-server-dom/client.browser.js") ||
+        cleanId.includes("vendor\\react-server-dom\\client.browser.js")
+      ) {
+        const isProd = process.env.NODE_ENV === "production";
+        const cjsFile = isProd
+          ? "./cjs/react-server-dom-webpack-client.browser.production.js"
+          : "./cjs/react-server-dom-webpack-client.browser.development.js";
+
+        return {
+          code: `export * from "${cjsFile}";`,
+          map: null,
+        };
+      }
+
+      // Transform the actual CJS files to ESM
+      if (
+        (cleanId.includes("vendor/react-server-dom/cjs/") ||
+          cleanId.includes("vendor\\react-server-dom\\cjs\\")) &&
+        cleanId.includes("client.browser")
+      ) {
+        let transformed = code;
+
+        // Extract the license comment to preserve it
+        const licenseMatch = transformed.match(/^\/\*\*[\s\S]*?\*\//);
+        const license = licenseMatch ? licenseMatch[0] : "";
+        if (license) {
+          transformed = transformed.slice(license.length);
+        }
+
+        // Remove "use strict" and the conditional IIFE wrapper
+        transformed = transformed.replace(
+          /^\s*["']use strict["'];\s*["']production["']\s*!==\s*process\.env\.NODE_ENV\s*&&\s*\(function\s*\(\)\s*\{/,
+          ""
+        );
+
+        // Remove the closing of the conditional IIFE at the end
+        transformed = transformed.replace(/\}\)\(\);?\s*$/, "");
+
+        // Replace require('react') and require('react-dom') with imports
+        transformed = transformed.replace(
+          /var\s+React\s*=\s*require\s*\(\s*["']react["']\s*\)\s*,[\s\n]+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
+          'import React from "react";\nimport ReactDOM from "react-dom";\nvar '
+        );
+
+        // Transform exports.xyz = function() to export function xyz()
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=\s*function\s*\(/g,
+          "export function $1("
+        );
+
+        // Transform exports.xyz = value to export const xyz = value
+        transformed = transformed.replace(
+          /exports\.(\w+)\s*=/g,
+          "export const $1 ="
+        );
+
+        // Reconstruct with license at the top
+        transformed = license + "\n" + transformed;
+
+        return {
+          code: transformed,
+          map: null,
+        };
+      }
+
+      return null;
+    },
+  };
+}
+

package/src/vite/package-resolution.ts

@@ -0,0 +1,125 @@
+/**
+ * Package Resolution Utilities
+ *
+ * Handles detection of workspace vs npm install context and generates
+ * appropriate aliases and exclude lists for Vite configuration.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import packageJson from "../../package.json" with { type: "json" };
+
+/**
+ * The canonical name used in virtual entries (without scope)
+ */
+const VIRTUAL_PACKAGE_NAME = "rsc-router";
+
+/**
+ * Get the published package name (e.g., "@ivogt/rsc-router")
+ */
+export function getPublishedPackageName(): string {
+  return packageJson.name;
+}
+
+/**
+ * Check if the package is installed from npm (scoped) vs workspace (unscoped)
+ *
+ * In workspace development:
+ * - Package is installed as "rsc-router" via pnpm workspace alias
+ * - The scoped name (@ivogt/rsc-router) doesn't exist in node_modules
+ *
+ * When installed from npm:
+ * - Package is installed as "@ivogt/rsc-router"
+ * - We need aliases to map "rsc-router/*" to "@ivogt/rsc-router/*"
+ */
+export function isInstalledFromNpm(): boolean {
+  const packageName = getPublishedPackageName();
+  // Check if the scoped package exists in node_modules
+  return existsSync(resolve(process.cwd(), "node_modules", packageName));
+}
+
+/**
+ * Check if we're in a monorepo/workspace development context
+ */
+export function isWorkspaceDevelopment(): boolean {
+  return !isInstalledFromNpm();
+}
+
+/**
+ * Subpaths that need to be excluded from Vite's dependency optimization
+ * and potentially aliased
+ */
+const PACKAGE_SUBPATHS = [
+  "",
+  "/browser",
+  "/client",
+  "/server",
+  "/rsc",
+  "/ssr",
+  "/internal/deps/browser",
+  "/internal/deps/html-stream-client",
+  "/internal/deps/ssr",
+  "/internal/deps/rsc",
+] as const;
+
+/**
+ * Generate the list of modules to exclude from Vite's dependency optimization.
+ *
+ * We include both the published name and the virtual name because
+ * Vite's optimizer runs before alias resolution.
+ */
+export function getExcludeDeps(): string[] {
+  const packageName = getPublishedPackageName();
+  const excludes: string[] = [];
+
+  for (const subpath of PACKAGE_SUBPATHS) {
+    // Add scoped package paths
+    excludes.push(`${packageName}${subpath}`);
+    // Add virtual/aliased paths (before alias resolution)
+    if (packageName !== VIRTUAL_PACKAGE_NAME) {
+      excludes.push(`${VIRTUAL_PACKAGE_NAME}${subpath}`);
+    }
+  }
+
+  return excludes;
+}
+
+/**
+ * Subpaths that need aliasing (subset of PACKAGE_SUBPATHS)
+ */
+const ALIAS_SUBPATHS = [
+  "/internal/deps/browser",
+  "/internal/deps/ssr",
+  "/internal/deps/rsc",
+  "/internal/deps/html-stream-client",
+  "/internal/deps/html-stream-server",
+  "/browser",
+  "/client",
+  "/server",
+  "/rsc",
+  "/ssr",
+] as const;
+
+/**
+ * Generate aliases to map virtual package paths to the actual published package.
+ *
+ * Only needed when installed from npm, where the package is under @ivogt/rsc-router
+ * but virtual entries import from rsc-router/*.
+ *
+ * Returns empty object in workspace development where rsc-router resolves directly.
+ */
+export function getPackageAliases(): Record<string, string> {
+  if (isWorkspaceDevelopment()) {
+    // No aliases needed - rsc-router resolves directly
+    return {};
+  }
+
+  const packageName = getPublishedPackageName();
+  const aliases: Record<string, string> = {};
+
+  for (const subpath of ALIAS_SUBPATHS) {
+    aliases[`${VIRTUAL_PACKAGE_NAME}${subpath}`] = `${packageName}${subpath}`;
+  }
+
+  return aliases;
+}