rwsdk 1.0.0-beta.43 → 1.0.0-beta.44

package/dist/runtime/client/client.js

@@ -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

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>

package/dist/runtime/lib/router.js

@@ -1,55 +1,66 @@
 import React from "react";
 import { isValidElementType } from "react-is";
 const METHOD_VERBS = ["delete", "get", "head", "patch", "post", "put"];
-export function matchPath(routePath, requestPath) {
+const pathCache = new Map();
+function compilePath(routePath) {
+    const cached = pathCache.get(routePath);
+    if (cached)
+        return cached;
     // Check for invalid pattern: multiple colons in a segment (e.g., /:param1:param2/)
     if (routePath.includes(":")) {
         const segments = routePath.split("/");
         for (const segment of segments) {
             if ((segment.match(/:/g) || []).length > 1) {
-                throw new Error(`Invalid route pattern: segment "${segment}" in "${routePath}" contains multiple colons.`);
+                throw new Error(`RedwoodSDK: Invalid route pattern: segment "${segment}" in "${routePath}" contains multiple colons. Each route parameter should use a single colon (e.g., ":id"). Check for accidental double colons ("::").`);
             }
         }
     }
     // Check for invalid pattern: double wildcard (e.g., /**/)
     if (routePath.indexOf("**") !== -1) {
-        throw new Error(`Invalid route pattern: "${routePath}" contains "**". Use "*" for a single wildcard segment.`);
+        throw new Error(`RedwoodSDK: Invalid route pattern: "${routePath}" contains "**". Use "*" for a single wildcard segment. Double wildcards are not supported.`);
     }
-    const pattern = routePath
-        .replace(/:[a-zA-Z0-9]+/g, "([^/]+)") // Convert :param to capture group
-        .replace(/\*/g, "(.*)"); // Convert * to wildcard capture group
-    const regex = new RegExp(`^${pattern}$`);
-    const matches = requestPath.match(regex);
-    if (!matches) {
-        return null;
+    const isStatic = !routePath.includes(":") && !routePath.includes("*");
+    if (isStatic) {
+        const result = { isStatic: true, regex: null, paramMap: [] };
+        pathCache.set(routePath, result);
+        return result;
     }
-    // Revised parameter extraction:
-    const params = {};
-    let currentMatchIndex = 1; // Regex matches are 1-indexed
-    // This regex finds either a named parameter token (e.g., ":id") or a wildcard star token ("*").
+    const paramMap = [];
+    let wildcardCounter = 0;
     const tokenRegex = /:([a-zA-Z0-9_]+)|\*/g;
     let matchToken;
-    let wildcardCounter = 0;
-    // Ensure regex starts from the beginning of the routePath for each call if it's stateful (it is with /g)
-    tokenRegex.lastIndex = 0;
     while ((matchToken = tokenRegex.exec(routePath)) !== null) {
-        // Ensure we have a corresponding match from the regex execution
-        if (matches[currentMatchIndex] === undefined) {
-            // This case should ideally not be hit if routePath and pattern generation are correct
-            // and all parts of the regex matched.
-            // Consider logging a warning or throwing an error if critical.
-            break;
-        }
         if (matchToken[1]) {
-            // This token is a named parameter (e.g., matchToken[1] is "id" for ":id")
-            params[matchToken[1]] = matches[currentMatchIndex];
+            paramMap.push({ name: matchToken[1], isWildcard: false });
         }
         else {
-            // This token is a wildcard "*"
-            params[`$${wildcardCounter}`] = matches[currentMatchIndex];
-            wildcardCounter++;
+            paramMap.push({ name: `$${wildcardCounter++}`, isWildcard: true });
         }
-        currentMatchIndex++;
+    }
+    const pattern = routePath
+        .replace(/:[a-zA-Z0-9_]+/g, "([^/]+)") // Convert :param to capture group
+        .replace(/\*/g, "(.*)"); // Convert * to wildcard capture group
+    const result = {
+        isStatic: false,
+        regex: new RegExp(`^${pattern}$`),
+        paramMap,
+    };
+    pathCache.set(routePath, result);
+    return result;
+}
+export function matchPath(routePath, requestPath) {
+    const compiled = compilePath(routePath);
+    if (compiled.isStatic) {
+        return routePath === requestPath ? {} : null;
+    }
+    const matches = requestPath.match(compiled.regex);
+    if (!matches) {
+        return null;
+    }
+    const params = {};
+    for (let i = 0; i < compiled.paramMap.length; i++) {
+        const param = compiled.paramMap[i];
+        params[param.name] = matches[i + 1];
     }
     return params;
 }
@@ -58,7 +69,10 @@ function flattenRoutes(routes) {
         if (Array.isArray(route)) {
             return [...acc, ...flattenRoutes(route)];
         }
-        return [...acc, route];
+        return [
+            ...acc,
+            route,
+        ];
     }, []);
 }
 function isMethodHandlers(handler) {
@@ -95,15 +109,41 @@ function getHandlerForMethod(methodHandlers, method) {
 }
 export function defineRoutes(routes) {
     const flattenedRoutes = flattenRoutes(routes);
+    const compiledRoutes = flattenedRoutes.map((route) => {
+        if (typeof route === "function") {
+            return { type: "middleware", handler: route };
+        }
+        if (typeof route === "object" &&
+            route !== null &&
+            "__rwExcept" in route &&
+            route.__rwExcept === true) {
+            return { type: "except", handler: route };
+        }
+        const routeDef = route;
+        const compiledPath = compilePath(routeDef.path);
+        return {
+            type: "definition",
+            path: routeDef.path,
+            handler: routeDef.handler,
+            layouts: routeDef.layouts,
+            isStatic: compiledPath.isStatic,
+            regex: compiledPath.regex ?? undefined,
+            paramNames: compiledPath.paramMap
+                .filter((p) => !p.isWildcard)
+                .map((p) => p.name),
+            wildcardCount: compiledPath.paramMap.filter((p) => p.isWildcard).length,
+        };
+    });
     return {
         routes: flattenedRoutes,
         async handle({ request, renderPage, getRequestInfo, onError, runWithRequestInfoOverrides, rscActionHandler, }) {
+            const requestInfo = getRequestInfo();
             const url = new URL(request.url);
             let path = url.pathname;
-            // Must end with a trailing slash.
             if (path !== "/" && !path.endsWith("/")) {
                 path = path + "/";
             }
+            requestInfo.path = path;
             // --- Helpers ---
             // (Hoisted for readability)
             function parseHandlers(handler) {
@@ -117,7 +157,17 @@ export function defineRoutes(routes) {
             }
             function renderElement(element) {
                 const requestInfo = getRequestInfo();
+                // Try to preserve the component name from the element's type
+                const elementType = element.type;
+                const componentName = typeof elementType === "function" && elementType.name
+                    ? elementType.name
+                    : "Element";
                 const Element = () => element;
+                // Set the name for better debugging
+                Object.defineProperty(Element, "name", {
+                    value: componentName,
+                    configurable: true,
+                });
                 return renderPage(requestInfo, Element, onError);
             }
             async function handleMiddlewareResult(result) {
@@ -129,95 +179,193 @@ export function defineRoutes(routes) {
                 }
                 return undefined;
             }
+            function isExceptHandler(route) {
+                return route.type === "except";
+            }
+            async function executeExceptHandlers(error, startIndex) {
+                // Search backwards from startIndex to find the most recent except handler
+                for (let i = startIndex; i >= 0; i--) {
+                    const route = compiledRoutes[i];
+                    if (isExceptHandler(route)) {
+                        try {
+                            const result = await route.handler.handler(error, getRequestInfo());
+                            const handled = await handleMiddlewareResult(result);
+                            if (handled) {
+                                return handled;
+                            }
+                            // If the handler didn't return a Response or JSX, continue to next handler (further back)
+                        }
+                        catch (nextError) {
+                            // If the except handler itself throws, try the next one (further back)
+                            return await executeExceptHandlers(nextError, i - 1);
+                        }
+                    }
+                }
+                // No handler found, throw to top-level onError
+                onError(error);
+                throw error;
+            }
             // --- Main flow ---
             let firstRouteDefinitionEncountered = false;
             let actionHandled = false;
             const handleAction = async () => {
-                if (!actionHandled && url.searchParams.has("__rsc_action_id")) {
-                    getRequestInfo().rw.actionResult = await rscActionHandler(request);
+                // Handle RSC actions once per request, based on the incoming URL.
+                if (!actionHandled) {
+                    const url = new URL(request.url);
+                    if (url.searchParams.has("__rsc_action_id")) {
+                        requestInfo.rw.actionResult = await rscActionHandler(request);
+                    }
                     actionHandled = true;
                 }
             };
-            for (const route of flattenedRoutes) {
-                if (typeof route === "function") {
-                    // This is a global middleware.
-                    const result = await route(getRequestInfo());
-                    const handled = await handleMiddlewareResult(result);
-                    if (handled) {
-                        return handled; // Short-circuit
-                    }
-                    continue;
-                }
-                // This is a RouteDefinition.
-                // The first time we see one, we handle any RSC actions.
-                if (!firstRouteDefinitionEncountered) {
-                    firstRouteDefinitionEncountered = true;
-                    await handleAction();
-                }
-                const params = matchPath(route.path, path);
-                if (!params) {
-                    continue; // Not a match, keep going.
-                }
-                // Resolve handler if method-based routing
-                let handler;
-                if (isMethodHandlers(route.handler)) {
-                    const requestMethod = request.method;
-                    // Handle OPTIONS request
-                    if (requestMethod === "OPTIONS" &&
-                        !route.handler.config?.disableOptions) {
-                        return handleOptionsRequest(route.handler);
+            try {
+                let currentRouteIndex = 0;
+                for (const route of compiledRoutes) {
+                    // Skip except handlers during normal execution
+                    if (route.type === "except") {
+                        currentRouteIndex++;
+                        continue;
                     }
-                    // Try to find handler for the request method
-                    handler = getHandlerForMethod(route.handler, requestMethod);
-                    if (!handler) {
-                        // Method not supported for this route
-                        if (!route.handler.config?.disable405) {
-                            return handleMethodNotAllowed(route.handler);
+                    if (route.type === "middleware") {
+                        // This is a global middleware.
+                        try {
+                            const result = await route.handler(getRequestInfo());
+                            const handled = await handleMiddlewareResult(result);
+                            if (handled) {
+                                return handled; // Short-circuit
+                            }
+                        }
+                        catch (error) {
+                            return await executeExceptHandlers(error, currentRouteIndex);
                         }
-                        // If 405 is disabled, continue to next route
+                        currentRouteIndex++;
                         continue;
                     }
-                }
-                else {
-                    handler = route.handler;
-                }
-                // Found a match: run route-specific middlewares, then the final component, then stop.
-                return await runWithRequestInfoOverrides({ params }, async () => {
-                    const { routeMiddlewares, componentHandler } = parseHandlers(handler);
-                    // Route-specific middlewares
-                    for (const mw of routeMiddlewares) {
-                        const result = await mw(getRequestInfo());
-                        const handled = await handleMiddlewareResult(result);
-                        if (handled) {
-                            return handled;
+                    // This is a RouteDefinition (route.type === "definition").
+                    // The first time we see one, we handle any RSC actions.
+                    if (!firstRouteDefinitionEncountered) {
+                        firstRouteDefinitionEncountered = true;
+                        try {
+                            await handleAction();
+                        }
+                        catch (error) {
+                            return await executeExceptHandlers(error, currentRouteIndex);
                         }
                     }
-                    // Final component/handler
-                    if (isRouteComponent(componentHandler)) {
-                        const requestInfo = getRequestInfo();
-                        const WrappedComponent = wrapWithLayouts(wrapHandlerToThrowResponses(componentHandler), route.layouts || [], requestInfo);
-                        if (!isClientReference(componentHandler)) {
-                            requestInfo.rw.pageRouteResolved = Promise.withResolvers();
+                    let params = null;
+                    if (route.isStatic) {
+                        if (route.path === path) {
+                            params = {};
                         }
-                        return await renderPage(requestInfo, WrappedComponent, onError);
                     }
-                    // Handle non-component final handler (e.g., returns new Response)
-                    const tailResult = await componentHandler(getRequestInfo());
-                    const handledTail = await handleMiddlewareResult(tailResult);
-                    if (handledTail) {
-                        return handledTail;
+                    else if (route.regex) {
+                        const matches = path.match(route.regex);
+                        if (matches) {
+                            params = {};
+                            for (let i = 0; i < route.paramNames.length; i++) {
+                                params[route.paramNames[i]] = matches[i + 1];
+                            }
+                            for (let i = 0; i < route.wildcardCount; i++) {
+                                params[`$${i}`] = matches[route.paramNames.length + i + 1];
+                            }
+                        }
                     }
-                    return new Response("Response not returned from route handler", {
-                        status: 500,
-                    });
-                });
+                    if (!params) {
+                        currentRouteIndex++;
+                        continue; // Not a match, keep going.
+                    }
+                    // Resolve handler if method-based routing
+                    let handler;
+                    if (isMethodHandlers(route.handler)) {
+                        const requestMethod = request.method;
+                        // Handle OPTIONS request
+                        if (requestMethod === "OPTIONS" &&
+                            !route.handler.config?.disableOptions) {
+                            return handleOptionsRequest(route.handler);
+                        }
+                        // Try to find handler for the request method
+                        handler = getHandlerForMethod(route.handler, requestMethod);
+                        if (!handler) {
+                            // Method not supported for this route
+                            if (!route.handler.config?.disable405) {
+                                return handleMethodNotAllowed(route.handler);
+                            }
+                            // If 405 is disabled, continue to next route
+                            currentRouteIndex++;
+                            continue;
+                        }
+                    }
+                    else {
+                        handler = route.handler;
+                    }
+                    // Found a match: run route-specific middlewares, then the final component, then stop.
+                    try {
+                        return await runWithRequestInfoOverrides({ params }, async () => {
+                            const { routeMiddlewares, componentHandler } = parseHandlers(handler);
+                            // Route-specific middlewares
+                            for (const mw of routeMiddlewares) {
+                                const result = await mw(getRequestInfo());
+                                const handled = await handleMiddlewareResult(result);
+                                if (handled) {
+                                    return handled;
+                                }
+                            }
+                            // Final component/handler
+                            if (isRouteComponent(componentHandler)) {
+                                const requestInfo = getRequestInfo();
+                                const WrappedComponent = wrapWithLayouts(wrapHandlerToThrowResponses(componentHandler), route.layouts || [], requestInfo);
+                                if (!isClientReference(componentHandler)) {
+                                    requestInfo.rw.pageRouteResolved = Promise.withResolvers();
+                                }
+                                return await renderPage(requestInfo, WrappedComponent, onError);
+                            }
+                            // Handle non-component final handler (e.g., returns new Response)
+                            const tailResult = await componentHandler(getRequestInfo());
+                            const handledTail = await handleMiddlewareResult(tailResult);
+                            if (handledTail) {
+                                return handledTail;
+                            }
+                            const handlerName = typeof componentHandler === "function" &&
+                                componentHandler.name
+                                ? componentHandler.name
+                                : "anonymous";
+                            const errorMessage = `Route handler did not return a Response or React element.
+
+Route: ${route.path}
+Matched path: ${path}
+Method: ${request.method}
+Handler: ${handlerName}
+
+Route handlers must return one of:
+  - A Response object (e.g., \`new Response("OK")\`)
+  - A React element (e.g., \`<div>Hello</div>\`)
+  - \`void\` (if handled by middleware earlier in the chain)`;
+                            return new Response(errorMessage, {
+                                status: 500,
+                                headers: { "Content-Type": "text/plain" },
+                            });
+                        });
+                    }
+                    catch (error) {
+                        return await executeExceptHandlers(error, currentRouteIndex);
+                    }
+                }
+                // If we've gotten this far, no route was matched.
+                // We still need to handle a possible action if the app has no route definitions at all.
+                if (!firstRouteDefinitionEncountered) {
+                    try {
+                        await handleAction();
+                    }
+                    catch (error) {
+                        return await executeExceptHandlers(error, compiledRoutes.length - 1);
+                    }
+                }
+                return new Response("Not Found", { status: 404 });
             }
-            // If we've gotten this far, no route was matched.
-            // We still need to handle a possible action if the app has no route definitions at all.
-            if (!firstRouteDefinitionEncountered) {
-                await handleAction();
+            catch (error) {
+                // Top-level catch for any unhandled errors
+                return await executeExceptHandlers(error, compiledRoutes.length - 1);
             }
-            return new Response("Not Found", { status: 404 });
         },
     };
 }
@@ -260,6 +408,9 @@ export function defineRoutes(routes) {
  */
 export function route(path, handler) {
     let normalizedPath = path;
+    if (!normalizedPath.startsWith("/")) {
+        normalizedPath = "/" + normalizedPath;
+    }
     if (!normalizedPath.endsWith("/")) {
         normalizedPath = normalizedPath + "/";
     }
@@ -293,6 +444,25 @@ export function route(path, handler) {
 export function index(handler) {
     return route("/", handler);
 }
+/**
+ * Defines an error handler that catches errors from routes, middleware, and RSC actions.
+ *
+ * @example
+ * // Global error handler
+ * except((error, requestInfo) => {
+ *   console.error(error);
+ *   return new Response("Internal Server Error", { status: 500 });
+ * })
+ *
+ * @example
+ * // Error handler that returns a React component
+ * except((error) => {
+ *   return <ErrorPage error={error} />;
+ * })
+ */
+export function except(handler) {
+    return { __rwExcept: true, handler };
+}
 /**
  * Prefixes a group of routes with a path.
  *
@@ -312,25 +482,83 @@ export function index(handler) {
  *   ]),
  * ])
  */
+function joinPaths(p1, p2) {
+    // Normalize p1: ensure it doesn't end with / (except if it's just "/")
+    const part1 = p1 === "/" ? "/" : p1.endsWith("/") ? p1.slice(0, -1) : p1;
+    // Normalize p2: ensure it starts with /
+    const part2 = p2.startsWith("/") ? p2 : `/${p2}`;
+    return part1 + part2;
+}
 export function prefix(prefixPath, routes) {
+    // Normalize prefix path
+    let normalizedPrefix = prefixPath;
+    if (!normalizedPrefix.startsWith("/")) {
+        normalizedPrefix = "/" + normalizedPrefix;
+    }
+    if (!normalizedPrefix.endsWith("/")) {
+        normalizedPrefix = normalizedPrefix + "/";
+    }
+    // Check if prefix has parameters
+    const hasParams = normalizedPrefix.includes(":") || normalizedPrefix.includes("*");
+    // Create a pattern for matching: if prefix has params, append wildcard to match any path under it
+    const matchPattern = hasParams
+        ? normalizedPrefix.endsWith("/")
+            ? normalizedPrefix.slice(0, -1) + "/*"
+            : normalizedPrefix + "/*"
+        : normalizedPrefix;
     const prefixed = routes.map((r) => {
         if (typeof r === "function") {
             const middleware = (requestInfo) => {
-                const url = new URL(requestInfo.request.url);
-                if (url.pathname.startsWith(prefixPath)) {
-                    return r(requestInfo);
+                const path = requestInfo.path;
+                // Check if path matches the prefix pattern
+                let matches = false;
+                let prefixParams = {};
+                if (hasParams) {
+                    // Use matchPath to check if path matches and extract params
+                    const params = matchPath(matchPattern, path);
+                    if (params) {
+                        matches = true;
+                        prefixParams = params;
+                    }
+                }
+                else {
+                    // For static prefixes, use simple string matching
+                    if (path === normalizedPrefix || path.startsWith(normalizedPrefix)) {
+                        matches = true;
+                    }
+                }
+                if (matches) {
+                    // Merge prefix params with existing params
+                    const mergedParams = { ...requestInfo.params, ...prefixParams };
+                    // Create a new requestInfo with merged params
+                    const modifiedRequestInfo = {
+                        ...requestInfo,
+                        params: mergedParams,
+                    };
+                    return r(modifiedRequestInfo);
                 }
                 return;
             };
             return middleware;
         }
+        if (typeof r === "object" &&
+            r !== null &&
+            "__rwExcept" in r &&
+            r.__rwExcept === true) {
+            // Pass through ExceptHandler as-is
+            return r;
+        }
         if (Array.isArray(r)) {
             // Recursively process nested route arrays
             return prefix(prefixPath, r);
         }
         const routeDef = r;
+        // Use joinPaths to properly combine paths
+        const combinedPath = joinPaths(prefixPath, routeDef.path);
+        // Normalize double slashes
+        const normalizedCombinedPath = combinedPath.replace(/\/+/g, "/");
         return {
-            path: prefixPath + routeDef.path,
+            path: normalizedCombinedPath,
             handler: routeDef.handler,
             ...(routeDef.layouts && { layouts: routeDef.layouts }),
         };
@@ -383,7 +611,7 @@ export const wrapHandlerToThrowResponses = (handler) => {
  *
  * @example
  * // Define a layout component
- * function BlogLayout({ children }: { children: React.ReactNode }) {
+ * function BlogLayout({ children }: { children?: React.ReactNode }) {
  *   return (
  *     <div>
  *       <nav>Blog Navigation</nav>
@@ -404,6 +632,13 @@ export function layout(LayoutComponent, routes) {
             // Pass through middleware as-is
             return route;
         }
+        if (typeof route === "object" &&
+            route !== null &&
+            "__rwExcept" in route &&
+            route.__rwExcept === true) {
+            // Pass through ExceptHandler as-is
+            return route;
+        }
         if (Array.isArray(route)) {
             // Recursively process nested route arrays
             return layout(LayoutComponent, route);

package/dist/runtime/lib/router.test.js

@@ -1,6 +1,6 @@
 import React from "react";
 import { describe, expect, it } from "vitest";
-import { defineRoutes, layout, matchPath, prefix, render, route, } from "./router";
+import { defineRoutes, except, layout, matchPath, prefix, render, route, } from "./router";
 describe("matchPath", () => {
     // Test case 1: Static paths
     it("should match static paths", () => {
@@ -62,6 +62,7 @@ describe("defineRoutes - Request Handling Behavior", () => {
     const createMockDependencies = () => {
         const mockRequestInfo = {
             request: new Request("http://localhost:3000/"),
+            path: "/",
             params: {},
             ctx: {},
             rw: {
@@ -293,6 +294,109 @@ describe("defineRoutes - Request Handling Behavior", () => {
             expect(executionOrder).toEqual(["prefixedMiddleware"]);
             expect(await response.text()).toBe("From prefixed middleware");
         });
+        it("should pass prefix parameters to route handlers", async () => {
+            let capturedParams = null;
+            const TaskDetailPage = (requestInfo) => {
+                capturedParams = requestInfo.params;
+                return React.createElement("div", {}, "Task Detail");
+            };
+            const router = defineRoutes([
+                ...prefix("/tasks/:containerId", [route("/", TaskDetailPage)]),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/tasks/123/");
+            const request = new Request("http://localhost:3000/tasks/123/");
+            await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(capturedParams).toEqual({ containerId: "123" });
+        });
+        it("should pass prefix parameters to middlewares within a parameterized prefix", async () => {
+            const executionOrder = [];
+            let capturedParams = null;
+            const prefixedMiddleware = (requestInfo) => {
+                executionOrder.push("prefixedMiddleware");
+                capturedParams = requestInfo.params;
+            };
+            const PageComponent = () => {
+                executionOrder.push("PageComponent");
+                return React.createElement("div", {}, "Page");
+            };
+            const router = defineRoutes([
+                ...prefix("/tasks/:containerId", [
+                    prefixedMiddleware,
+                    route("/", PageComponent),
+                ]),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/tasks/123/");
+            const request = new Request("http://localhost:3000/tasks/123/");
+            await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(executionOrder).toEqual(["prefixedMiddleware", "PageComponent"]);
+            // The wildcard captures the trailing slash as an empty string
+            expect(capturedParams).toEqual({ containerId: "123", $0: "" });
+        });
+        it("should pass prefix parameters to route handlers (array)", async () => {
+            let capturedParamsInMiddleware = null;
+            let capturedParamsInComponent = null;
+            const middleware = (requestInfo) => {
+                capturedParamsInMiddleware = requestInfo.params;
+            };
+            const Component = (requestInfo) => {
+                capturedParamsInComponent = requestInfo.params;
+                return React.createElement("div", {}, "Component");
+            };
+            const router = defineRoutes([
+                ...prefix("/tasks/:containerId", [route("/", [middleware, Component])]),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/tasks/123/");
+            const request = new Request("http://localhost:3000/tasks/123/");
+            await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(capturedParamsInMiddleware).toEqual({ containerId: "123" });
+            expect(capturedParamsInComponent).toEqual({ containerId: "123" });
+        });
+        it("should match even if prefix has a trailing slash", async () => {
+            let capturedParams = null;
+            const TaskDetailPage = (requestInfo) => {
+                capturedParams = requestInfo.params;
+                return React.createElement("div", {}, "Task Detail");
+            };
+            const router = defineRoutes([
+                ...prefix("/tasks/:containerId/", [route("/", TaskDetailPage)]),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/tasks/123/");
+            const request = new Request("http://localhost:3000/tasks/123/");
+            await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(capturedParams).toEqual({ containerId: "123" });
+        });
     });
     describe("RSC Action Handling", () => {
         it("should handle RSC actions before the first route definition", async () => {
@@ -884,4 +988,242 @@ describe("defineRoutes - Request Handling Behavior", () => {
             expect(await response.text()).toBe("Rendered: Element");
         });
     });
+    describe("except - Error Handling", () => {
+        it("should catch errors from global middleware", async () => {
+            const errorMessage = "Middleware error";
+            const middleware = () => {
+                throw new Error(errorMessage);
+            };
+            const errorHandler = except((error) => {
+                return new Response(`Caught: ${error instanceof Error ? error.message : String(error)}`, {
+                    status: 500,
+                });
+            });
+            const router = defineRoutes([
+                middleware,
+                errorHandler,
+                route("/test/", () => React.createElement("div")),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/test/");
+            const request = new Request("http://localhost:3000/test/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(response.status).toBe(500);
+            expect(await response.text()).toBe(`Caught: ${errorMessage}`);
+        });
+        it("should catch errors from route handlers (components)", async () => {
+            const errorMessage = "Component error";
+            const PageComponent = () => {
+                throw new Error(errorMessage);
+            };
+            const errorHandler = except((error) => {
+                return new Response(`Caught: ${error instanceof Error ? error.message : String(error)}`, {
+                    status: 500,
+                });
+            });
+            const router = defineRoutes([
+                errorHandler,
+                route("/test/", PageComponent),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/test/");
+            const request = new Request("http://localhost:3000/test/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(response.status).toBe(500);
+            expect(await response.text()).toBe(`Caught: ${errorMessage}`);
+        });
+        it("should catch errors from route handlers (functions)", async () => {
+            const errorMessage = "Handler error";
+            const routeHandler = () => {
+                throw new Error(errorMessage);
+            };
+            const errorHandler = except((error) => {
+                return new Response(`Caught: ${error instanceof Error ? error.message : String(error)}`, {
+                    status: 500,
+                });
+            });
+            const router = defineRoutes([
+                errorHandler,
+                route("/test/", routeHandler),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/test/");
+            const request = new Request("http://localhost:3000/test/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(response.status).toBe(500);
+            expect(await response.text()).toBe(`Caught: ${errorMessage}`);
+        });
+        it("should catch errors from RSC actions", async () => {
+            const errorMessage = "RSC action error";
+            const errorHandler = except((error) => {
+                return new Response(`Caught: ${error instanceof Error ? error.message : String(error)}`, {
+                    status: 500,
+                });
+            });
+            const router = defineRoutes([
+                errorHandler,
+                route("/test/", () => React.createElement("div")),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/test/?__rsc_action_id=test");
+            deps.mockRscActionHandler = async () => {
+                throw new Error(errorMessage);
+            };
+            const request = new Request("http://localhost:3000/test/?__rsc_action_id=test");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(response.status).toBe(500);
+            expect(await response.text()).toBe(`Caught: ${errorMessage}`);
+        });
+        it("should use the most recent except handler before the error", async () => {
+            const errorMessage = "Route error";
+            const firstHandler = except((error) => {
+                return new Response("First handler", { status: 500 });
+            });
+            const secondHandler = except((error) => {
+                return new Response("Second handler", { status: 500 });
+            });
+            const PageComponent = () => {
+                throw new Error(errorMessage);
+            };
+            const router = defineRoutes([
+                firstHandler,
+                secondHandler,
+                route("/test/", PageComponent),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/test/");
+            const request = new Request("http://localhost:3000/test/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            // Should use the second handler (most recent before the route)
+            expect(response.status).toBe(500);
+            expect(await response.text()).toBe("Second handler");
+        });
+        it("should try next except handler if current one throws", async () => {
+            const errorMessage = "Route error";
+            const firstHandler = except(() => {
+                throw new Error("First handler error");
+            });
+            const secondHandler = except((error) => {
+                return new Response(`Caught by second: ${error instanceof Error ? error.message : String(error)}`, {
+                    status: 500,
+                });
+            });
+            const PageComponent = () => {
+                throw new Error(errorMessage);
+            };
+            const router = defineRoutes([
+                secondHandler, // Outer handler
+                firstHandler, // Inner handler (closer to route)
+                route("/test/", PageComponent),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/test/");
+            const request = new Request("http://localhost:3000/test/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            // Should catch the error from the first handler with the second handler
+            expect(response.status).toBe(500);
+            expect(await response.text()).toBe("Caught by second: First handler error");
+        });
+        it("should return JSX element from except handler", async () => {
+            const errorMessage = "Route error";
+            function ErrorComponent() {
+                return React.createElement("div", {}, "Error Page");
+            }
+            const errorHandler = except(() => {
+                return React.createElement(ErrorComponent);
+            });
+            const PageComponent = () => {
+                throw new Error(errorMessage);
+            };
+            const router = defineRoutes([
+                errorHandler,
+                route("/test/", PageComponent),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/test/");
+            const request = new Request("http://localhost:3000/test/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(await response.text()).toBe("Rendered: ErrorComponent");
+        });
+        it("should work with prefix and layout", async () => {
+            const errorMessage = "Route error";
+            const errorHandler = except((error) => {
+                return new Response(`Caught: ${error instanceof Error ? error.message : String(error)}`, {
+                    status: 500,
+                });
+            });
+            const PageComponent = () => {
+                throw new Error(errorMessage);
+            };
+            const Layout = ({ children }) => {
+                return React.createElement("div", {}, children);
+            };
+            const router = defineRoutes([
+                errorHandler,
+                layout(Layout, [prefix("/api", [route("/test/", PageComponent)])]),
+            ]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/api/test/");
+            const request = new Request("http://localhost:3000/api/test/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(response.status).toBe(500);
+            expect(await response.text()).toBe(`Caught: ${errorMessage}`);
+        });
+    });
 });

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

@@ -3,6 +3,7 @@ export interface DefaultAppContext {
 }
 export interface RequestInfo<Params = any, AppContext = DefaultAppContext> {
     request: Request;
+    path: string;
     params: Params;
     ctx: AppContext;
     rw: RwContext;

package/dist/runtime/requestInfo/utils.js

@@ -9,6 +9,7 @@ export const constructWithDefaultRequestInfo = (overrides = {}) => {
     const { rw: rwOverrides, ...otherRequestInfoOverrides } = overrides;
     const defaultRequestInfo = {
         request: new Request("http://localhost/"),
+        path: "/",
         params: {},
         ctx: {},
         cf: {

package/dist/runtime/requestInfo/worker.js

@@ -17,7 +17,8 @@ export const requestInfo = Object.freeze(requestInfoBase);
 export function getRequestInfo() {
     const store = requestInfoStore.getStore();
     if (!store) {
-        throw new Error("Request context not found");
+        throw new Error("RedwoodSDK: Request context not found. getRequestInfo() can only be called within the request lifecycle (e.g., in a route handler, middleware, or server action).\n\n" +
+            "For detailed troubleshooting steps, see: https://docs.rwsdk.com/guides/troubleshooting#request-context-errors");
     }
     return store;
 }

package/dist/runtime/worker.js

@@ -11,11 +11,11 @@ import { defineRoutes } from "./lib/router";
 import { generateNonce } from "./lib/utils";
 export * from "./requestInfo/types";
 export const defineApp = (routes) => {
+    const router = defineRoutes(routes);
     return {
         __rwRoutes: routes,
         fetch: async (request, env, cf) => {
             globalThis.__webpack_require__ = ssrWebpackRequire;
-            const router = defineRoutes(routes);
             // context(justinvdm, 5 Feb 2025): Serve assets requests using the assets service binding
             // todo(justinvdm, 5 Feb 2025): Find a way to avoid this so asset requests are served directly
             // rather than first needing to go through the worker
@@ -63,6 +63,10 @@ export const defineApp = (routes) => {
             }
             try {
                 const url = new URL(request.url);
+                let path = url.pathname;
+                if (path !== "/" && !path.endsWith("/")) {
+                    path = path + "/";
+                }
                 const isRSCRequest = url.searchParams.has("__rsc") ||
                     request.headers.get("accept")?.includes("text/x-component");
                 const isAction = url.searchParams.has("__rsc_action_id");
@@ -83,6 +87,7 @@ export const defineApp = (routes) => {
                 };
                 const outerRequestInfo = {
                     request,
+                    path,
                     cf,
                     params: {},
                     ctx: {},

package/dist/vite/runDirectivesScan.mjs

@@ -298,7 +298,9 @@ export const runDirectivesScan = async ({ rootConfig, environments, clientFiles,
         });
     }
     catch (e) {
-        throw new Error(`RWSDK directive scan failed:\n${e.stack}`);
+        throw new Error(`RedwoodSDK: Directive scan failed. This often happens due to syntax errors in files using "use client" or "use server". Check your directive files for issues.\n\n` +
+            `For detailed troubleshooting steps, see: https://docs.rwsdk.com/guides/troubleshooting#directive-scan-errors\n\n` +
+            `${e.stack}`);
     }
     finally {
         deferredLog("✔ (rwsdk) Done scanning for 'use client' and 'use server' directives.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rwsdk",
-  "version": "1.0.0-beta.43",
+  "version": "1.0.0-beta.44",
   "description": "Build fast, server-driven webapps on Cloudflare with SSR, RSC, and realtime",
   "type": "module",
   "bin": {
@@ -182,6 +182,7 @@
     "puppeteer-core": "~24.22.0",
     "react-is": "~19.1.0",
     "rsc-html-stream": "~0.0.6",
+    "server-only": "^0.0.1",
     "tmp-promise": "~3.0.3",
     "ts-morph": "~27.0.0",
     "unique-names-generator": "~4.7.1",