Stabilize client-side onError (#14546)

* Stabilize client-side onError

* Docs

Author: brophdawg11

.changeset/small-flowers-drive.md

@@ -0,0 +1,5 @@
+---
+"react-router": minor
+---
+
+Stabilize `<HydratedRouter onError>`/`<RouterProvider onError>`

docs/how-to/error-boundary.md

@@ -11,7 +11,7 @@ title: Error Boundaries
 
 To avoid rendering an empty page to users, route modules will automatically catch errors in your code and render the closest `ErrorBoundary`.
 
-Error boundaries are not intended for error reporting or rendering form validation errors. Please see [Form Validation](./form-validation) and [Error Reporting](./error-reporting) instead.
+Error boundaries are not intended for rendering form validation errors or error reporting. Please see [Form Validation](./form-validation) and [Error Reporting](./error-reporting) instead.
 
 ## 1. Add a root error boundary
 

docs/how-to/error-reporting.md

@@ -4,22 +4,28 @@ title: Error Reporting
 
 # Error Reporting
 
-[MODES: framework]
+[MODES: framework,data]
 
 <br/>
 <br/>
 
-React Router catches errors in your route modules and sends them to [error boundaries](./error-boundary) to prevent blank pages when errors occur. However, ErrorBoundary isn't sufficient for logging and reporting errors. To access these caught errors, use the handleError export of the server entry module.
+React Router catches errors in your route modules and sends them to [error boundaries](./error-boundary) to prevent blank pages when errors occur. However, `ErrorBoundary` isn't sufficient for logging and reporting errors.
 
-## 1. Reveal the server entry
+## Server Errors
 
-If you don't see `entry.server.tsx` in your app directory, you're using a default entry. Reveal it with this cli command:
+[modes: framework]
+
+To access these caught errors on the server, use the `handleError` export of the server entry module.
+
+### 1. Reveal the server entry
+
+If you don't see [`entry.server.tsx`][entryserver] in your app directory, you're using a default entry. Reveal it with this cli command:
 
 ```shellscript nonumber
-react-router reveal
+react-router reveal entry.server
 ```
 
-## 2. Export your error handler
+### 2. Export your error handler
 
 This function is called whenever React Router catches an error in your application on the server.
 
@@ -39,3 +45,75 @@ export const handleError: HandleErrorFunction = (
   }
 };
 ```
+
+## Client Errors
+
+To access these caught errors on the client, use the `onError` prop on your [`HydratedRouter`][hydratedrouter] or [`RouterProvider`][routerprovider] component.
+
+### Framework Mode
+
+[modes: framework]
+
+#### 1. Reveal the client entry
+
+If you don't see [`entry.client.tsx`][entryclient] in your app directory, you're using a default entry. Reveal it with this cli command:
+
+```shellscript nonumber
+react-router reveal entry.client
+```
+
+#### 2. Add your error handler
+
+This function is called whenever React Router catches an error in your application on the client.
+
+```tsx filename=entry.client.tsx
+import { type ClientOnErrorFunction } from "react-router";
+
+const onError: ClientOnErrorFunction = (
+  error,
+  { location, params, unstable_pattern, errorInfo },
+) => {
+  myReportError(error, location, errorInfo);
+
+  // make sure to still log the error so you can see it
+  console.error(error, errorInfo);
+};
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter onError={onError} />
+    </StrictMode>,
+  );
+});
+```
+
+### Data Mode
+
+[modes: data]
+
+This function is called whenever React Router catches an error in your application on the client.
+
+```tsx
+import { type ClientOnErrorFunction } from "react-router";
+
+const onError: ClientOnErrorFunction = (
+  error,
+  { location, params, unstable_pattern, errorInfo },
+) => {
+  myReportError(error, location, errorInfo);
+
+  // make sure to still log the error so you can see it
+  console.error(error, errorInfo);
+};
+
+function App() {
+  return <RouterProvider onError={onError} />;
+}
+```
+
+[entryserver]: ../api/framework-conventions/entry.server.tsx
+[entryclient]: ../api/framework-conventions/entry.client.tsx
+[hydratedrouter]: ../api//framework-routers/HydratedRouter
+[routerprovider]: ../api/data-routers/RouterProvider

integration/browser-entry-test.ts

@@ -146,7 +146,7 @@ test("allows users to pass an onError function to HydratedRouter", async ({
             document,
             <StrictMode>
               <HydratedRouter
-                unstable_onError={(error, errorInfo) => {
+                onError={(error, errorInfo) => {
                   console.log(error.message, JSON.stringify(errorInfo))
                 }}
               />

packages/react-router/__tests__/dom/client-on-error-test.tsx

@@ -44,7 +44,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
     await waitFor(() => screen.getByText("lazy error!"));
 
@@ -75,7 +75,7 @@ describe(`handleError`, () => {
       },
     ]);
 
-    render(<RouterProvider router={router} unstable_onError={spy} />);
+    render(<RouterProvider router={router} onError={spy} />);
 
     await waitFor(() => screen.getByText("Error:middleware error!"));
 
@@ -104,7 +104,7 @@ describe(`handleError`, () => {
       },
     ]);
 
-    render(<RouterProvider router={router} unstable_onError={spy} />);
+    render(<RouterProvider router={router} onError={spy} />);
 
     await waitFor(() => screen.getByText("Error:loader error!"));
 
@@ -134,7 +134,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -170,7 +170,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -202,7 +202,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -234,7 +234,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() =>
@@ -269,7 +269,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.fetch("key", "0", "/fetch"));
@@ -299,7 +299,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() =>
@@ -335,7 +335,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -380,7 +380,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -429,7 +429,7 @@ describe(`handleError`, () => {
     }
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -484,7 +484,7 @@ describe(`handleError`, () => {
     }
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -540,7 +540,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -591,7 +591,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));

packages/react-router/index.ts

@@ -103,7 +103,7 @@ export { AwaitContextProvider as UNSAFE_AwaitContextProvider } from "./lib/conte
 export type {
   AwaitProps,
   IndexRouteProps,
-  unstable_ClientOnErrorFunction,
+  ClientOnErrorFunction,
   LayoutRouteProps,
   MemoryRouterOpts,
   MemoryRouterProps,