rwsdk 1.0.0-beta.42 → 1.0.0-beta.44

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

@@ -13,7 +13,11 @@ export declare const fetchTransport: Transport;
  * making the page interactive. Call this from your client entry point.
  *
  * @param transport - Custom transport for server communication (defaults to fetchTransport)
- * @param hydrateRootOptions - Options passed to React's hydrateRoot
+ * @param hydrateRootOptions - Options passed to React's `hydrateRoot`. Supports all React hydration options including:
+ *                             - `onUncaughtError`: Handler for uncaught errors (async errors, event handler errors).
+ *                               If not provided, defaults to logging errors to console.
+ *                             - `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 onActionResponse - Optional hook invoked when an action returns a Response;
@@ -34,6 +38,23 @@ export declare const fetchTransport: Transport;
  * initClient({ handleResponse });
  *
  * @example
+ * // With error handling
+ * initClient({
+ *   hydrateRootOptions: {
+ *     onUncaughtError: (error, errorInfo) => {
+ *       console.error("Uncaught error:", error);
+ *       // Send to monitoring service
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *     onCaughtError: (error, errorInfo) => {
+ *       console.error("Caught error:", error);
+ *       // Handle errors from error boundaries
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *   },
+ * });
+ *
+ * @example
  * // With custom React hydration options
  * initClient({
  *   hydrateRootOptions: {

package/dist/runtime/client/client.js

@@ -105,7 +105,11 @@ export const fetchTransport = (transportContext) => {
  * making the page interactive. Call this from your client entry point.
  *
  * @param transport - Custom transport for server communication (defaults to fetchTransport)
- * @param hydrateRootOptions - Options passed to React's hydrateRoot
+ * @param hydrateRootOptions - Options passed to React's `hydrateRoot`. Supports all React hydration options including:
+ *                             - `onUncaughtError`: Handler for uncaught errors (async errors, event handler errors).
+ *                               If not provided, defaults to logging errors to console.
+ *                             - `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 onActionResponse - Optional hook invoked when an action returns a Response;
@@ -126,6 +130,23 @@ export const fetchTransport = (transportContext) => {
  * initClient({ handleResponse });
  *
  * @example
+ * // With error handling
+ * initClient({
+ *   hydrateRootOptions: {
+ *     onUncaughtError: (error, errorInfo) => {
+ *       console.error("Uncaught error:", error);
+ *       // Send to monitoring service
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *     onCaughtError: (error, errorInfo) => {
+ *       console.error("Caught error:", error);
+ *       // Handle errors from error boundaries
+ *       sendToSentry(error, errorInfo);
+ *     },
+ *   },
+ * });
+ *
+ * @example
  * // With custom React hydration options
  * initClient({
  *   hydrateRootOptions: {
@@ -158,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>