From 4009af8d3c4831b0654a9ddb686f2852ad346eeb Mon Sep 17 00:00:00 2001
From: Gabe Kangas <gabek@real-ity.com>
Date: Mon, 13 Mar 2023 00:00:35 -0700
Subject: [PATCH] Add note about error boundaries

---
 web/components/_COMPONENT_HOW_TO.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/web/components/_COMPONENT_HOW_TO.md b/web/components/_COMPONENT_HOW_TO.md
index db517bfd0..56194427c 100644
--- a/web/components/_COMPONENT_HOW_TO.md
+++ b/web/components/_COMPONENT_HOW_TO.md
@@ -64,6 +64,33 @@ But why _this_ style?
 
 See the discussion on the PR that introduced this pattern: [#2082](https://github.com/owncast/owncast/pull/2082).
 
+## Error Boundaries
+
+Components that have substantial state and internal functionality should be wrapped in an [Error Boundary](https://reactjs.org/docs/error-boundaries.html). This allows for catching unexpected errors and displaying a fallback UI.
+
+Components that are stateless views are unlikely to throw exceptions and don't require an error boundary.
+
+The `ComponentError` component is a pre-built error state that can be used to display an error message and a bug reporting button.
+
+### Example
+
+```tsx
+import { ErrorBoundary } from 'react-error-boundary';
+
+<ErrorBoundary
+      // eslint-disable-next-line react/no-unstable-nested-components
+      fallbackRender={({ error: e, resetErrorBoundary }) => (
+        <ComponentError
+          componentName="BrowserNotifyModal"
+          message={e.message}
+          retryFunction={resetErrorBoundary}
+        />
+      )}
+    >
+		<YourFunctionality/>
+</ErrorBoundary
+```
+
 ## Storybook
 
 We use [Storybook](https://storybook.js.org/) to create a component library where we can see and interact with each component.