feat!: remove CatchBoundary logic (#5781)

Co-authored-by: Michaël De Boey <info@michaeldeboey.be>

.changeset/eight-squids-greet.md

@@ -0,0 +1,6 @@
+---
+"@remix-run/react": major
+"@remix-run/server-runtime": major
+---
+
+Remove `v2_errorBoundary` flag and `CatchBoundary` logic

docs/api/conventions.md

@@ -178,10 +178,6 @@ title: Conventions
 
 [Moved →][moved-41]
 
-### CatchBoundary
-
-[Moved →][moved-42]
-
 ### ErrorBoundary
 
 [Moved →][moved-43]
@@ -239,7 +235,6 @@ title: Conventions
 [moved-39]: ../route/links
 [moved-40]: ../route/links#htmllinkdescriptor
 [moved-41]: ../route/links#pagelinkdescriptor
-[moved-42]: ../route/catch-boundary
 [moved-43]: ../route/error-boundary
 [moved-44]: ../route/handle
 [moved-45]: ../route/should-revalidate

docs/pages/api-development-strategy.md

@@ -53,7 +53,6 @@ The lifecycle is thus either:
 | Flag                     | Description                                                           |
 | ------------------------ | --------------------------------------------------------------------- |
 | `v2_dev`                 | Enable the new development server (including HMR/HDR support)         |
-| `v2_errorBoundary`       | Combine `ErrorBoundary`/`CatchBoundary` into a single `ErrorBoundary` |
 | `v2_headers`             | Leverage ancestor `headers` if children do not export `headers`       |
 | `v2_normalizeFormMethod` | Normalize `useNavigation().formMethod` to be an uppercase HTTP Method |
 | `v2_routeConvention`     | Enable the flat routes style of file-based routing                    |

docs/pages/faq.md

@@ -220,11 +220,4 @@ Again, `formData.getAll()` is often all you need, we encourage you to give it a
 [form-data]: https://developer.mozilla.org/en-US/docs/Web/API/FormData
 [query-string]: https://www.npmjs.com/package/query-string
 [ramda]: https://www.npmjs.com/package/ramda
-
-## What's the difference between `CatchBoundary` & `ErrorBoundary`?
-
-Error boundaries render when your application throws an error and you had no clue it was going to happen. Most apps just go blank or have spinners spin forever. In remix the error boundary renders and you have granular control over it.
-
-Catch boundaries render when you decide in a loader that you can't proceed down the happy path to render the UI you want (auth required, record not found, etc.), so you throw a response and let some catch boundary up the tree handle it.
-
 [watch-on-you-tube]: https://www.youtube.com/watch?v=w2i-9cYxSdc&ab_channel=Remix

docs/route/error-boundary.md

@@ -1,30 +1,56 @@
 ---
 title: ErrorBoundary
+new: true
 ---
 
 # `ErrorBoundary`
 
-<docs-warning>The behaviors of `CatchBoundary` and `ErrorBoundary` are changing in v2. You can prepare for this change at your convenience with the `v2_errorBoundary` future flag. For instructions on making this change see the [v2 guide][v2guide].</docs-warning>
+A Remix `ErrorBoundary` component works just like normal React [error boundaries][error-boundaries], but with a few extra capabilities. When there is an error in your route component, the `ErrorBoundary` will be rendered in its place, nested inside any parent routes. `ErrorBoundary` components also render when there is an error in the `loader` or `action` functions for a route, so all errors for that route may be handled in one spot.
 
-An `ErrorBoundary` is a React component that renders whenever there is an error anywhere on the route, either during rendering or during data loading. We use the word "error" to mean an uncaught exception; something you didn't anticipate happening. You can intentionally throw a `Response` to render the `CatchBoundary`, but everything else that is thrown is handled by the `ErrorBoundary`.
+The most common use-cases tend to be:
 
-A Remix `ErrorBoundary` component works just like normal React [error boundaries][error-boundaries], but with a few extra capabilities. When there is an error in your route component, the `ErrorBoundary` will be rendered in its place, nested inside any parent routes. `ErrorBoundary` components also render when there is an error in the `loader` or `action` functions for a route, so all errors for that route may be handled in one spot.
+- You may intentionally throw a 4xx `Response` to trigger an error UI
+  - Throwing a 400 on bad user input
+  - Throwing a 401 for unauthorized access
+  - Throwing a 404 when you can't find requested data
+- React may unintentionally throw an `Error` if it encounters a runtime error during rendering
 
-An `ErrorBoundary` component receives one prop: the `error` that occurred.
+To obtain the thrown object, you can use the [`useRouteError`][use-route-error] hook. When a `Response` is thrown, it will be automatically unwrapped into an `ErrorResponse` instance with `state`/`statusText`/`data` fields so that you don't need to bother with `await response.json()` in your component. To differentiate thrown `Response`'s from thrown `Error`'s' you can use the [`isRouteErrorResponse`][is-route-error-response] utility.
 
 ```tsx
-export function ErrorBoundary({ error }) {
-  return (
-    <div>
-      <h1>Error</h1>
-      <p>{error.message}</p>
-      <p>The stack trace is:</p>
-      <pre>{error.stack}</pre>
-    </div>
-  );
+import {
+  isRouteErrorResponse,
+  useRouteError,
+} from "@remix-run/react";
+
+export function ErrorBoundary() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error)) {
+    return (
+      <div>
+        <h1>
+          {error.status} {error.statusText}
+        </h1>
+        <p>{error.data}</p>
+      </div>
+    );
+  } else if (error instanceof Error) {
+    return (
+      <div>
+        <h1>Error</h1>
+        <p>{error.message}</p>
+        <p>The stack trace is:</p>
+        <pre>{error.stack}</pre>
+      </div>
+    );
+  } else {
+    return <h1>Unknown Error</h1>;
+  }
 }
 ```
 
 [error-boundaries]: https://reactjs.org/docs/error-boundaries.html
-[error-boundary-v2]: ./error-boundary-v2
-[v2guide]: ../pages/v2#catchboundary-and-errorboundary
+[rr-error-boundary]: https://reactrouter.com/en/main/route/error-element
+[use-route-error]: ../hooks/use-route-error
+[is-route-error-response]: ../utils/is-route-error-response

docs/utils/is-route-error-response.md

@@ -7,4 +7,28 @@ toc: false
 
 <docs-info>This util is simply a re-export of [React Router's `isRouteErrorResponse`][rr-isrouteerrorresponse].</docs-info>
 
+When a response is thrown from an action or loader, it will be unwrapped into an `ErrorResponse` so that your component doesn't have to deal with the complexity of unwrapping it (which would require React state and effects to deal with the promise returned from `res.json()`)
+
+```tsx
+import { json } from "@remix-run/node"; // or cloudflare/deno
+
+export function action() {
+  throw json(
+    { message: "email is required" },
+    { status: 400, statusText: "Bad Request" }
+  );
+}
+
+export function ErrorBoundary() {
+  const error = useRouteError();
+  if (isRouteErrorResponse(error)) {
+    error.status; // 400
+    error.statusText; // Bad Request
+    error.data; // { "message: "email is required" }
+  }
+}
+```
+
+<docs-info>If the user visits a route that does not match any routes in the app, Remix itself will throw a 404 response.</docs-info>
+
 [rr-isrouteerrorresponse]: https://reactrouter.com/utils/is-route-error-response

integration/action-test.ts

@@ -20,7 +20,6 @@ test.describe("actions", () => {
       config: {
         future: {
           v2_routeConvention: true,
-          v2_errorBoundary: true,
           v2_normalizeFormMethod: true,
         },
       },