rwsdk 1.0.0-beta.43 → 1.0.0-beta.45

package/dist/runtime/client/client.d.ts

@@ -19,7 +19,7 @@ export declare const fetchTransport: Transport;
  *                             - `onCaughtError`: Handler for errors caught by error boundaries
  *                             - `onRecoverableError`: Handler for recoverable errors
  * @param handleResponse - Custom response handler for navigation errors (navigation GETs)
- * @param onHydrationUpdate - Callback invoked after a new RSC payload has been committed on the client
+ * @param onHydrated - Callback invoked after a new RSC payload has been committed on the client
  * @param onActionResponse - Optional hook invoked when an action returns a Response;
  *                           return true to signal that the response has been handled and
  *                           default behaviour (e.g. redirects) should be skipped
@@ -64,10 +64,10 @@ export declare const fetchTransport: Transport;
  *   },
  * });
  */
-export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, onHydrationUpdate, onActionResponse, }?: {
+export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, }?: {
     transport?: Transport;
     hydrateRootOptions?: HydrationOptions;
     handleResponse?: (response: Response) => boolean;
-    onHydrationUpdate?: () => void;
+    onHydrated?: () => void;
     onActionResponse?: (actionResponse: ActionResponseData) => boolean | void;
 }) => Promise<void>;

package/dist/runtime/client/client.js

@@ -111,7 +111,7 @@ export const fetchTransport = (transportContext) => {
  *                             - `onCaughtError`: Handler for errors caught by error boundaries
  *                             - `onRecoverableError`: Handler for recoverable errors
  * @param handleResponse - Custom response handler for navigation errors (navigation GETs)
- * @param onHydrationUpdate - Callback invoked after a new RSC payload has been committed on the client
+ * @param onHydrated - Callback invoked after a new RSC payload has been committed on the client
  * @param onActionResponse - Optional hook invoked when an action returns a Response;
  *                           return true to signal that the response has been handled and
  *                           default behaviour (e.g. redirects) should be skipped
@@ -156,11 +156,11 @@ export const fetchTransport = (transportContext) => {
  *   },
  * });
  */
-export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, onHydrationUpdate, onActionResponse, } = {}) => {
+export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, onHydrated, onActionResponse, } = {}) => {
     const transportContext = {
         setRscPayload: () => { },
         handleResponse,
-        onHydrationUpdate,
+        onHydrated,
         onActionResponse,
     };
     let transportCallServer = transport(transportContext);
@@ -179,7 +179,7 @@ export const initClient = async ({ transport = fetchTransport, hydrateRootOption
     };
     const rootEl = document.getElementById("hydrate-root");
     if (!rootEl) {
-        throw new Error('no element with id "hydrate-root"');
+        throw new Error('RedwoodSDK: No element with id "hydrate-root" found in the document. This element is required for hydration. Ensure your Document component contains a <div id="hydrate-root">{children}</div>.');
     }
     let rscPayload;
     // context(justinvdm, 18 Jun 2025): We inject the RSC payload
@@ -198,7 +198,7 @@ export const initClient = async ({ transport = fetchTransport, hydrateRootOption
         React.useEffect(() => {
             if (!streamData)
                 return;
-            transportContext.onHydrationUpdate?.();
+            transportContext.onHydrated?.();
         }, [streamData]);
         return (_jsx(_Fragment, { children: streamData
                 ? React.use(streamData).node

package/dist/runtime/client/navigation.d.ts

@@ -29,8 +29,8 @@ export declare function navigate(href: string, options?: NavigateOptions): Promi
  * // Basic usage
  * import { initClient, initClientNavigation } from "rwsdk/client";
  *
- * const { handleResponse, onHydrationUpdate } = initClientNavigation();
- * initClient({ handleResponse, onHydrationUpdate });
+ * const { handleResponse, onHydrated } = initClientNavigation();
+ * initClient({ handleResponse, onHydrated });
  *
  * @example
  * // With custom scroll behavior
@@ -58,5 +58,5 @@ export declare function navigate(href: string, options?: NavigateOptions): Promi
  */
 export declare function initClientNavigation(opts?: ClientNavigationOptions): {
     handleResponse: (response: Response) => boolean;
-    onHydrationUpdate: () => void;
+    onHydrated: () => void;
 };

package/dist/runtime/client/navigation.js

@@ -78,8 +78,8 @@ function saveScrollPosition(x, y) {
  * // Basic usage
  * import { initClient, initClientNavigation } from "rwsdk/client";
  *
- * const { handleResponse, onHydrationUpdate } = initClientNavigation();
- * initClient({ handleResponse, onHydrationUpdate });
+ * const { handleResponse, onHydrated } = initClientNavigation();
+ * initClient({ handleResponse, onHydrated });
  *
  * @example
  * // With custom scroll behavior
@@ -134,9 +134,9 @@ export function initClientNavigation(opts = {}) {
     if (opts.cacheStorage && typeof globalThis !== "undefined") {
         globalThis.__rsc_cacheStorage = opts.cacheStorage;
     }
-    function onHydrationUpdate() {
+    function onHydrated() {
         // After each RSC hydration/update, increment generation and evict old caches,
-        // then warm the navigation cache based on any <link rel="prefetch"> tags
+        // then warm the navigation cache based on any <link rel="x-prefetch"> tags
         // rendered for the current location.
         onNavigationCommit(undefined, opts.cacheStorage);
         void preloadFromLinkTags(undefined, undefined, opts.cacheStorage);
@@ -144,6 +144,6 @@ export function initClientNavigation(opts = {}) {
     // Return callbacks for use with initClient
     return {
         handleResponse,
-        onHydrationUpdate,
+        onHydrated,
     };
 }

package/dist/runtime/client/navigationCache.d.ts

@@ -57,7 +57,7 @@ export declare function evictOldGenerationCaches(env?: NavigationCacheEnvironmen
  */
 export declare function onNavigationCommit(env?: NavigationCacheEnvironment, cacheStorage?: NavigationCacheStorage): void;
 /**
- * Scan the document for `<link rel="prefetch" href="...">` elements that point
+ * Scan the document for `<link rel="x-prefetch" href="...">` elements that point
  * to same-origin paths and prefetch their RSC navigation responses into the
  * Cache API.
  *

package/dist/runtime/client/navigationCache.js

@@ -5,30 +5,22 @@ function getOrInitializeCacheState() {
     if (cacheState) {
         return cacheState;
     }
-    // Get or generate tabId
-    let tabId;
-    if (typeof window !== "undefined" && window.sessionStorage) {
+    let tabId = null;
+    if (typeof window !== "undefined") {
         try {
-            const stored = sessionStorage.getItem(TAB_ID_STORAGE_KEY);
-            if (stored) {
-                tabId = stored;
-            }
-            else {
-                tabId = crypto.randomUUID();
+            tabId = sessionStorage.getItem(TAB_ID_STORAGE_KEY);
+            if (!tabId) {
+                tabId = `${Date.now()}-${Math.floor(Math.random() * 1000000)}`;
                 sessionStorage.setItem(TAB_ID_STORAGE_KEY, tabId);
             }
         }
         catch {
-            // Fallback to in-memory tabId if sessionStorage is unavailable
-            tabId = crypto.randomUUID();
+            // sessionStorage might be unavailable
+            tabId = tabId || `${Date.now()}-${Math.floor(Math.random() * 1000000)}`;
         }
     }
-    else {
-        // Fallback for non-browser environments
-        tabId = crypto.randomUUID();
-    }
     cacheState = {
-        tabId,
+        tabId: tabId || "1",
         generation: 0,
         buildId: BUILD_ID,
     };
@@ -36,7 +28,7 @@ function getOrInitializeCacheState() {
 }
 function getCurrentCacheName() {
     const state = getOrInitializeCacheState();
-    return `rsc-prefetch:${state.buildId}:${state.tabId}:${state.generation}`;
+    return `rsc-x-prefetch:${state.buildId}:${state.tabId}:${state.generation}`;
 }
 function incrementGeneration() {
     const state = getOrInitializeCacheState();
@@ -135,6 +127,9 @@ export async function preloadNavigationUrl(rawUrl, env, cacheStorage) {
         const request = new Request(url.toString(), {
             method: "GET",
             redirect: "manual",
+            headers: {
+                "x-prefetch": "true",
+            },
         });
         const cacheName = getCurrentCacheName();
         const cache = await storage.open(cacheName);
@@ -221,7 +216,7 @@ export async function evictOldGenerationCaches(env, cacheStorage) {
         try {
             // List all cache names
             const cacheNames = await storage.keys();
-            const prefix = `rsc-prefetch:${buildId}:${tabId}:`;
+            const prefix = `rsc-x-prefetch:${buildId}:${tabId}:`;
             // Find all caches for this tab
             const tabCaches = cacheNames.filter((name) => name.startsWith(prefix));
             // Delete caches with generation numbers less than current
@@ -256,11 +251,16 @@ export async function evictOldGenerationCaches(env, cacheStorage) {
  * as complete and prepare for the next navigation cycle.
  */
 export function onNavigationCommit(env, cacheStorage) {
+    const runtimeEnv = env ?? getBrowserNavigationCacheEnvironment();
+    const storage = cacheStorage ?? createDefaultNavigationCacheStorage(runtimeEnv);
+    if (!storage) {
+        return;
+    }
     incrementGeneration();
-    void evictOldGenerationCaches(env, cacheStorage);
+    void evictOldGenerationCaches(env, storage);
 }
 /**
- * Scan the document for `<link rel="prefetch" href="...">` elements that point
+ * Scan the document for `<link rel="x-prefetch" href="...">` elements that point
  * to same-origin paths and prefetch their RSC navigation responses into the
  * Cache API.
  *
@@ -272,7 +272,7 @@ export async function preloadFromLinkTags(doc = document, env, cacheStorage) {
     if (typeof doc === "undefined") {
         return;
     }
-    const links = Array.from(doc.querySelectorAll('link[rel="prefetch"][href]'));
+    const links = Array.from(doc.querySelectorAll('link[rel="x-prefetch"][href]'));
     await Promise.all(links.map((link) => {
         const href = link.getAttribute("href");
         if (!href) {

package/dist/runtime/client/navigationCache.test.js

@@ -148,6 +148,19 @@ describe("navigationCache", () => {
             const requestUrl = new URL(request.url);
             expect(requestUrl.searchParams.has("__rsc")).toBe(true);
         });
+        it("should add x-prefetch header", async () => {
+            const env = {
+                isSecureContext: true,
+                origin: "https://example.com",
+                caches: mockCacheStorage,
+                fetch: mockFetch,
+            };
+            const url = new URL("https://example.com/test");
+            await preloadNavigationUrl(url, env);
+            const fetchCall = mockFetch.mock.calls[0];
+            const request = fetchCall[0];
+            expect(request.headers.get("x-prefetch")).toBe("true");
+        });
         it("should use custom cacheStorage when provided", async () => {
             const customCache = {
                 put: vi.fn().mockResolvedValue(undefined),
@@ -283,27 +296,27 @@ describe("navigationCache", () => {
             await preloadNavigationUrl(url, env);
             const openCall = mockCacheStorage.open.mock.calls[0];
             const cacheName = openCall[0];
-            const tabIdMatch = cacheName.match(/^rsc-prefetch:rwsdk:([^:]+):\d+$/);
+            const tabIdMatch = cacheName.match(/^rsc-x-prefetch:rwsdk:([^:]+):\d+$/);
             const tabId = tabIdMatch ? tabIdMatch[1] : "test-uuid-123";
             // Increment generation to 2 by calling onNavigationCommit twice
             onNavigationCommit(env);
             onNavigationCommit(env);
             // Mock cache names matching the actual tabId
             const allCacheNames = [
-                `rsc-prefetch:rwsdk:${tabId}:0`,
-                `rsc-prefetch:rwsdk:${tabId}:1`,
-                `rsc-prefetch:rwsdk:${tabId}:2`,
-                "rsc-prefetch:rwsdk:other-tab:0",
+                `rsc-x-prefetch:rwsdk:${tabId}:0`,
+                `rsc-x-prefetch:rwsdk:${tabId}:1`,
+                `rsc-x-prefetch:rwsdk:${tabId}:2`,
+                "rsc-x-prefetch:rwsdk:other-tab:0",
             ];
             mockCacheStorage.keys.mockResolvedValue(allCacheNames);
             await evictOldGenerationCaches(env);
             // Wait for the cleanup to execute
             await new Promise((resolve) => setTimeout(resolve, 10));
             // Should delete generations 0 and 1, but not 2 (current) or other-tab
-            expect(mockCacheStorage.delete).toHaveBeenCalledWith(`rsc-prefetch:rwsdk:${tabId}:0`);
-            expect(mockCacheStorage.delete).toHaveBeenCalledWith(`rsc-prefetch:rwsdk:${tabId}:1`);
-            expect(mockCacheStorage.delete).not.toHaveBeenCalledWith(`rsc-prefetch:rwsdk:${tabId}:2`);
-            expect(mockCacheStorage.delete).not.toHaveBeenCalledWith("rsc-prefetch:rwsdk:other-tab:0");
+            expect(mockCacheStorage.delete).toHaveBeenCalledWith(`rsc-x-prefetch:rwsdk:${tabId}:0`);
+            expect(mockCacheStorage.delete).toHaveBeenCalledWith(`rsc-x-prefetch:rwsdk:${tabId}:1`);
+            expect(mockCacheStorage.delete).not.toHaveBeenCalledWith(`rsc-x-prefetch:rwsdk:${tabId}:2`);
+            expect(mockCacheStorage.delete).not.toHaveBeenCalledWith("rsc-x-prefetch:rwsdk:other-tab:0");
         });
         it("should use custom cacheStorage when provided", async () => {
             // Get the actual tabId that will be used
@@ -317,7 +330,7 @@ describe("navigationCache", () => {
             await preloadNavigationUrl(url, env);
             const openCall = mockCacheStorage.open.mock.calls[0];
             const cacheName = openCall[0];
-            const tabIdMatch = cacheName.match(/^rsc-prefetch:rwsdk:([^:]+):\d+$/);
+            const tabIdMatch = cacheName.match(/^rsc-x-prefetch:rwsdk:([^:]+):\d+$/);
             const tabId = tabIdMatch ? tabIdMatch[1] : "test-uuid-123";
             const customStorage = {
                 open: vi.fn(),
@@ -325,8 +338,8 @@ describe("navigationCache", () => {
                 keys: vi
                     .fn()
                     .mockResolvedValue([
-                    `rsc-prefetch:rwsdk:${tabId}:0`,
-                    `rsc-prefetch:rwsdk:${tabId}:1`,
+                    `rsc-x-prefetch:rwsdk:${tabId}:0`,
+                    `rsc-x-prefetch:rwsdk:${tabId}:1`,
                 ]),
             };
             // Increment generation so there are old caches to delete
@@ -367,14 +380,14 @@ describe("navigationCache", () => {
         });
     });
     describe("preloadFromLinkTags", () => {
-        it("should preload URLs from prefetch link tags", async () => {
+        it("should preload URLs from x-prefetch link tags", async () => {
             const env = {
                 isSecureContext: true,
                 origin: "https://example.com",
                 caches: mockCacheStorage,
                 fetch: mockFetch,
             };
-            // Create a mock document with prefetch links
+            // Create a mock document with x-prefetch links
             const mockDoc = {
                 querySelectorAll: vi.fn().mockReturnValue([
                     {
@@ -450,7 +463,7 @@ describe("navigationCache", () => {
             await preloadNavigationUrl(url, env);
             const openCall = mockCacheStorage.open.mock.calls[0];
             const cacheName = openCall[0];
-            expect(cacheName).toMatch(/^rsc-prefetch:rwsdk:[^:]+:\d+$/);
+            expect(cacheName).toMatch(/^rsc-x-prefetch:rwsdk:[^:]+:\d+$/);
         });
     });
 });

package/dist/runtime/client/types.d.ts

@@ -23,7 +23,7 @@ export type TransportContext = {
      * This is useful for features like client-side navigation that want to run logic
      * after hydration/updates, e.g. warming navigation caches.
      */
-    onHydrationUpdate?: () => void;
+    onHydrated?: () => void;
     /**
      * Optional callback invoked when an action returns a Response.
      * Return true to signal that the response has been handled and

package/dist/runtime/entries/no-react-server-ssr-bridge.js

@@ -1,2 +1,2 @@
 "use strict";
-throw new Error("rwsdk: SSR bridge was resolved with 'react-server' condition. This is a bug - the SSR bridge should be intercepted by the esbuild plugin before reaching package.json exports. Please report this issue.");
+throw new Error("RedwoodSDK: SSR bridge was resolved with 'react-server' condition. This is a bug - the SSR bridge should be intercepted by the esbuild plugin before reaching package.json exports. Please report this issue at https://github.com/redwoodjs/sdk/issues.");

package/dist/runtime/entries/no-react-server.js

@@ -1,2 +1,4 @@
 "use strict";
-throw new Error("rwsdk: 'react-server' is not supported in this environment");
+throw new Error("RedwoodSDK: A client-only module was incorrectly resolved with the 'react-server' condition.\n\n" +
+    "This error occurs when modules like 'rwsdk/client', 'rwsdk/__ssr', or 'rwsdk/__ssr_bridge' are being imported in a React Server Components context.\n\n" +
+    "For detailed troubleshooting steps, see: https://docs.rwsdk.com/guides/troubleshooting#react-server-components-configuration-errors");

package/dist/runtime/entries/react-server-only.js

@@ -1,2 +1,2 @@
 "use strict";
-throw new Error("rwsdk: 'react-server' import condition needs to be used in this environment");
+throw new Error("RedwoodSDK: 'react-server' import condition needs to be used in this environment. This code should only run in React Server Components (RSC) context. Check that you're not importing server-only code in client components.");

package/dist/runtime/entries/worker.d.ts

@@ -1,3 +1,4 @@
+import "server-only";
 import "./types/worker";
 export * from "../error";
 export * from "../lib/types";

package/dist/runtime/entries/worker.js

@@ -1,3 +1,4 @@
+import "server-only";
 import "./types/worker";
 export * from "../error";
 export * from "../lib/types";

package/dist/runtime/lib/links.js

@@ -19,13 +19,13 @@ export function defineLinks(routes) {
     // Original implementation for route arrays
     routes.forEach((route) => {
         if (typeof route !== "string") {
-            throw new Error(`Invalid route: ${route}. Routes must be strings.`);
+            throw new Error(`RedwoodSDK: Invalid route: ${route}. Routes must be string literals. Ensure you're passing an array of route paths.`);
         }
     });
     const link = createLinkFunction();
     return ((path, params) => {
         if (!routes.includes(path)) {
-            throw new Error(`Invalid route: ${path}`);
+            throw new Error(`RedwoodSDK: Invalid route: ${path}. This route is not included in the routes array passed to defineLinks(). Check for typos or ensure the route is defined in your router.`);
         }
         return link(path, params);
     });
@@ -36,7 +36,7 @@ function createLinkFunction() {
         const expectsParams = hasRouteParameters(path);
         if (!params || Object.keys(params).length === 0) {
             if (expectsParams) {
-                throw new Error(`Route ${path} requires an object of parameters`);
+                throw new Error(`RedwoodSDK: Route ${path} requires an object of parameters (e.g., link("${path}", { id: "123" })).`);
             }
             return path;
         }
@@ -62,7 +62,7 @@ function interpolate(template, params) {
             const name = match[1];
             const value = params[name];
             if (value === undefined) {
-                throw new Error(`Missing parameter "${name}" for route ${template}`);
+                throw new Error(`RedwoodSDK: Missing parameter "${name}" for route ${template}. Ensure you're providing all required parameters in the params object.`);
             }
             result += encodeURIComponent(value);
             consumed.add(name);
@@ -71,7 +71,7 @@ function interpolate(template, params) {
             const key = `$${wildcardIndex}`;
             const value = params[key];
             if (value === undefined) {
-                throw new Error(`Missing parameter "${key}" for route ${template}`);
+                throw new Error(`RedwoodSDK: Missing parameter "${key}" for route ${template}. Wildcard routes use $0, $1, etc. as parameter keys.`);
             }
             result += encodeWildcardValue(value);
             consumed.add(key);
@@ -82,7 +82,7 @@ function interpolate(template, params) {
     result += template.slice(lastIndex);
     for (const key of Object.keys(params)) {
         if (!consumed.has(key)) {
-            throw new Error(`Parameter "${key}" is not used by route ${template}`);
+            throw new Error(`RedwoodSDK: Parameter "${key}" is not used by route ${template}. Check your params object for typos or remove unused parameters.`);
         }
     }
     TOKEN_REGEX.lastIndex = 0;

package/dist/runtime/lib/router.d.ts

@@ -6,6 +6,10 @@ type BivariantRouteHandler<T extends RequestInfo, R> = {
     bivarianceHack(requestInfo: T): R;
 }["bivarianceHack"];
 export type RouteMiddleware<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<React.JSX.Element | Response | void>>;
+export type ExceptHandler<T extends RequestInfo = RequestInfo> = {
+    __rwExcept: true;
+    handler: (error: unknown, requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>;
+};
 type RouteFunction<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<Response>>;
 type RouteComponent<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<React.JSX.Element | Response | void>>;
 type RouteHandler<T extends RequestInfo = RequestInfo> = RouteFunction<T> | RouteComponent<T> | readonly [...RouteMiddleware<T>[], RouteFunction<T> | RouteComponent<T>];
@@ -22,7 +26,7 @@ export type MethodHandlers<T extends RequestInfo = RequestInfo> = {
         [method: string]: RouteHandler<T>;
     };
 };
-export type Route<T extends RequestInfo = RequestInfo> = RouteMiddleware<T> | RouteDefinition<string, T> | readonly Route<T>[];
+export type Route<T extends RequestInfo = RequestInfo> = RouteMiddleware<T> | RouteDefinition<string, T> | ExceptHandler<T> | readonly Route<T>[];
 type NormalizedRouteDefinition<T extends RequestInfo = RequestInfo> = {
     path: string;
     handler: RouteHandler<T> | MethodHandlers<T>;
@@ -36,7 +40,7 @@ type TrimLeadingSlash<S extends string> = S extends `/${infer Rest}` ? TrimLeadi
 type NormalizePrefix<Prefix extends string> = TrimTrailingSlash<TrimLeadingSlash<Prefix>> extends "" ? "" : `/${TrimTrailingSlash<TrimLeadingSlash<Prefix>>}`;
 type NormalizePath<Path extends string> = TrimTrailingSlash<Path> extends "/" ? "/" : `/${TrimTrailingSlash<TrimLeadingSlash<Path>>}`;
 type JoinPaths<Prefix extends string, Path extends string> = NormalizePrefix<Prefix> extends "" ? NormalizePath<Path> : Path extends "/" ? NormalizePrefix<Prefix> : `${NormalizePrefix<Prefix>}${NormalizePath<Path>}`;
-type PrefixedRouteValue<Prefix extends string, Value> = Value extends RouteDefinition<infer Path, infer Req> ? RouteDefinition<JoinPaths<Prefix, Path>, Req> : Value extends readonly Route<any>[] ? PrefixedRouteArray<Prefix, Value> : Value;
+type PrefixedRouteValue<Prefix extends string, Value> = Value extends RouteDefinition<infer Path, infer Req> ? RouteDefinition<JoinPaths<Prefix, Path>, Req> : Value extends ExceptHandler<any> ? Value : Value extends readonly Route<any>[] ? PrefixedRouteArray<Prefix, Value> : Value;
 type PrefixedRouteArray<Prefix extends string, Routes extends readonly Route<any>[]> = Routes extends readonly [] ? [] : Routes extends readonly [infer Head, ...infer Tail] ? readonly [
     PrefixedRouteValue<Prefix, Head>,
     ...PrefixedRouteArray<Prefix, Tail extends readonly Route<any>[] ? Tail : []>
@@ -104,24 +108,22 @@ export declare function route<Path extends string, T extends RequestInfo = Reque
  */
 export declare function index<T extends RequestInfo = RequestInfo>(handler: RouteHandler<T>): RouteDefinition<"/", T>;
 /**
- * Prefixes a group of routes with a path.
+ * Defines an error handler that catches errors from routes, middleware, and RSC actions.
  *
  * @example
- * // Organize blog routes under /blog
- * const blogRoutes = [
- *   route("/", () => <BlogIndex />),
- *   route("/post/:id", ({ params }) => <BlogPost id={params.id} />),
- *   route("/admin", [isAuthenticated, () => <BlogAdmin />]),
- * ]
+ * // Global error handler
+ * except((error, requestInfo) => {
+ *   console.error(error);
+ *   return new Response("Internal Server Error", { status: 500 });
+ * })
  *
- * // In worker.tsx
- * defineApp([
- *   render(Document, [
- *     route("/", () => <HomePage />),
- *     prefix("/blog", blogRoutes),
- *   ]),
- * ])
+ * @example
+ * // Error handler that returns a React component
+ * except((error) => {
+ *   return <ErrorPage error={error} />;
+ * })
  */
+export declare function except<T extends RequestInfo = RequestInfo>(handler: (error: unknown, requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>): ExceptHandler<T>;
 export declare function prefix<Prefix extends string, T extends RequestInfo = RequestInfo, Routes extends readonly Route<T>[] = readonly Route<T>[]>(prefixPath: Prefix, routes: Routes): PrefixedRouteArray<Prefix, Routes>;
 export declare const wrapHandlerToThrowResponses: <T extends RequestInfo = RequestInfo>(handler: RouteFunction<T> | RouteComponent<T>) => RouteHandler<T>;
 /**
@@ -129,7 +131,7 @@ export declare const wrapHandlerToThrowResponses: <T extends RequestInfo = Reque
  *
  * @example
  * // Define a layout component
- * function BlogLayout({ children }: { children: React.ReactNode }) {
+ * function BlogLayout({ children }: { children?: React.ReactNode }) {
  *   return (
  *     <div>
  *       <nav>Blog Navigation</nav>