update docs

docs/route/error-boundary.md

@@ -4,6 +4,52 @@ title: ErrorBoundary
 
 # `ErrorBoundary`
 
-An `ErrorBoundary` is a React component that renders whenever anything is thrown anywhere on the route, either during rendering or during data loading. This can be a thrown `Response`/`Error` from a loader/action or an `Error` thrown during rendering. This `ErrorBoundary` is an implementation of the React Router []`errorElement`/`ErrorBoundary`][rr-error-boundary].
+<docs-info>The Remix `ErrorBoundary` is an implementation of the React Router [`errorElement`/`ErrorBoundary`][rr-error-boundary].</docs-info>
 
+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.
+
+The most common use-cases tend to be:
+
+- 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
+
+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
+import { isRouteErrorResponse } from "@remix-run/node";
+import { useRouteError } from "@remix-run/react";
+
+export function ErrorBoundary() {
+  let 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
 [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.md

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

@@ -0,0 +1,33 @@
+---
+title: isRouteErrorResponse
+---
+
+# `isRouteErrorResponse`
+
+<docs-info>This is just a re-export of the React Router [`isRouteErrorResponse`][rr-is-route-error-response] utility.</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()`)
+
+```jsx
+import { json } from "@remix-run/node";
+
+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-is-route-error-response]: https://reactrouter.com/en/main/utils/is-route-error-response