feat: implement lazy route definitions

packages/router/package.json

@@ -49,12 +49,13 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.2.14",
     "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
     "jsdom": "^28.1.0",
     "react": "^19.2.4",
     "tsdown": "^0.20.3",
     "typescript": "^5.7.0",
+    "urlpattern-polyfill": "^10.1.0",
     "vitest": "^4.0.18"
   }
 }

packages/router/src/Router/PendingOutlet.tsx

@@ -0,0 +1,17 @@
+import { type ReactNode, use } from "react";
+
+/**
+ * A component that suspends while lazy children are being resolved.
+ * Rendered as the outlet when a matched route has unresolved lazy children.
+ *
+ * This component is intentionally thin — it only calls use() to suspend.
+ * Promise creation and caching happen in the Router component.
+ */
+export function PendingOutlet({
+  promise,
+}: {
+  promise: Promise<void>;
+}): ReactNode {
+  use(promise);
+  return null;
+}

packages/router/src/Router/RouteRenderer.tsx

@@ -3,6 +3,7 @@ import { RouterContext } from "../context/RouterContext.js";
 import { RouteContext } from "../context/RouteContext.js";
 import type { MatchedRouteWithData, InternalRouteState } from "../types.js";
 import { useRouteStateCallbacks } from "./useRouteStateCallbacks.js";
+import { PendingOutlet } from "./PendingOutlet.js";
 
 export type RouteRendererProps = {
   matchedRoutes: MatchedRouteWithData[];
@@ -35,6 +36,7 @@ export function RouteRenderer({
     isPending,
     navigateAsync,
     updateCurrentEntryState,
+    lazyCache,
   } = routerContext;
 
   // Extract this route's state from internal structure
@@ -51,13 +53,24 @@ export function RouteRenderer({
     );
 
   // Create outlet for child routes
-  const outlet = useMemo(
-    () =>
-      index < matchedRoutes.length - 1 ? (
-        <RouteRenderer matchedRoutes={matchedRoutes} index={index + 1} />
-      ) : null,
-    [matchedRoutes, index],
-  );
+  const outlet = useMemo(() => {
+    if (index < matchedRoutes.length - 1) {
+      // Existing: child route matched, render it
+      return <RouteRenderer matchedRoutes={matchedRoutes} index={index + 1} />;
+    }
+
+    // If this route has unresolved lazy children, suspend via PendingOutlet
+    const currentRoute = matchedRoutes[index]?.route;
+    if (currentRoute && typeof currentRoute.children === "function") {
+      const promise = lazyCache.get(currentRoute);
+      // promise is guaranteed to exist — Router creates it before rendering
+      if (promise) {
+        return <PendingOutlet promise={promise} />;
+      }
+    }
+
+    return null;
+  }, [matchedRoutes, index, lazyCache]);
 
   // Extract id from route definition (if available)
   const routeId = (route as { id?: string }).id;

packages/router/src/Router/index.tsx

@@ -18,6 +18,7 @@ import {
   createBlockerRegistry,
 } from "../context/BlockerContext.js";
 import {
+  type InternalRouteDefinition,
   type NavigateOptions,
   type OnNavigateCallback,
   type FallbackMode,
@@ -107,6 +108,19 @@ export function Router({
 }: RouterProps): ReactNode {
   const routes = internalRoutes(inputRoutes);
 
+  // Cache of in-flight lazy resolution promises.
+  // Identity change (new Map reference) triggers matchedRoutesWithData recomputation.
+  const [lazyCache, setLazyCache] = useState(
+    () => new Map<InternalRouteDefinition, Promise<void>>(),
+  );
+
+  // Clear cache when routes prop changes (new route definitions)
+  const [prevRoutes, setPrevRoutes] = useState(inputRoutes);
+  if (prevRoutes !== inputRoutes) {
+    setPrevRoutes(inputRoutes);
+    setLazyCache(new Map());
+  }
+
   // Create adapter once based on browser capabilities and fallback setting
   const adapter = useMemo(() => createAdapter(fallback), [fallback]);
 
@@ -229,6 +243,11 @@ export function Router({
 
   // Match routes and execute loaders
   const matchedRoutesWithData = useMemo(() => {
+    // lazyCache identity change triggers recomputation after lazy children resolve.
+    // matchRoutes calls lazy functions internally — after resolution, the user's
+    // cache returns sync, producing a full match.
+    void lazyCache;
+
     if (!runLoaders) {
       // SSR/hydration without loader execution: match routes, data is undefined.
       // Routes with loaders are skipped (skipLoaders: true).
@@ -252,7 +271,56 @@ export function Router({
     const request = createLoaderRequest(urlObject);
     const signal = adapter.getIdleAbortSignal();
     return executeLoaders(matched, entryKey, request, signal);
-  }, [routes, adapter, urlObject, runLoaders, locationKey]);
+  }, [routes, adapter, urlObject, runLoaders, locationKey, lazyCache]);
+
+  // --- Lazy children resolution (async case) ---
+  // If matchRoutes returned a partial match (lazy function returned a Promise),
+  // the deepest matched route still has typeof children === 'function'.
+  // Call the function to get the Promise (same one matchRoutes got — user caches it),
+  // register it in lazyCache, and attach a .then() handler.
+  // This is setState-during-render on Router's OWN state, so React correctly
+  // discards the current render and re-renders with the updated cache.
+  if (matchedRoutesWithData) {
+    const lastMatch = matchedRoutesWithData[matchedRoutesWithData.length - 1];
+    if (
+      lastMatch &&
+      typeof lastMatch.route.children === "function" &&
+      !lazyCache.has(lastMatch.route)
+    ) {
+      const route = lastMatch.route;
+      const lazyFn = route.children as () =>
+        | InternalRouteDefinition[]
+        | Promise<InternalRouteDefinition[]>;
+      // Call the function — user's cache returns the same Promise that
+      // matchRoutes received, so no duplicate loading is triggered.
+      const result = lazyFn();
+      if (!Array.isArray(result)) {
+        // Async result — register promise and attach .then() handler
+        const triggerRerender = () => {
+          // Trigger Router re-render for the INITIAL PAGE LOAD case.
+          // During navigation, startTransition already retries the entire
+          // transition (including Router) when the promise resolves, so
+          // this is redundant. But on initial page load there is no
+          // transition — only the Suspense subtree retries. Router is above
+          // the Suspense boundary and won't re-render on its own. Without
+          // this, PendingOutlet would return null (promise resolved) and the
+          // outlet would be empty. This state update triggers Router to
+          // re-run matchRoutes, which calls the function → sync → full match.
+          setLazyCache((prev) => new Map(prev));
+        };
+        const voidPromise = result.then(triggerRerender, (error: unknown) => {
+          triggerRerender();
+          // Re-throw so the promise stays rejected for use() to catch
+          throw error;
+        });
+        // Register promise in cache. setState-during-render on own state:
+        // React discards this render and immediately re-renders with the
+        // updated cache. On re-render, the promise is found, RouteRenderer
+        // passes it to PendingOutlet, and use() suspends.
+        setLazyCache((prev) => new Map([...prev, [route, voidPromise]]));
+      }
+    }
+  }
 
   const locationState = locationEntry?.state;
   const locationInfo = locationEntry?.info;
@@ -264,6 +332,7 @@ export function Router({
       isPending,
       navigateAsync,
       updateCurrentEntryState,
+      lazyCache,
     }),
     [
       locationState,
@@ -272,6 +341,7 @@ export function Router({
       isPending,
       navigateAsync,
       updateCurrentEntryState,
+      lazyCache,
     ],
   );