[
{
"path": ".gitattributes",
"content": "* text=auto eol=lf\n"
},
{
"path": ".github/workflows/eslint.yml",
"content": "name: \"ESLint\"\non: [pull_request]\njobs:\n eslint:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - uses: pnpm/action-setup@v2\n with:\n version: 10\n - name: Install dependencies\n run: pnpm install --frozen-lockfile --recursive\n - name: Run ESLint\n run: pnpm lint\n"
},
{
"path": ".github/workflows/pending-changes.yml",
"content": "name: \"Pending changes\"\non: [pull_request]\njobs:\n pending-changes:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - uses: pnpm/action-setup@v2\n with:\n version: 10\n - name: Install dependencies\n run: pnpm install --frozen-lockfile --recursive\n - uses: nickcharlton/diff-check@main\n with:\n command: pnpm run compile\n"
},
{
"path": ".github/workflows/prettier.yml",
"content": "name: \"Prettier\"\non: [pull_request]\njobs:\n prettier:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - uses: pnpm/action-setup@v2\n with:\n version: 10\n - name: Install dependencies\n run: pnpm install --frozen-lockfile --recursive\n - name: Run Prettier\n run: pnpm run prettier:ci\n"
},
{
"path": ".github/workflows/typescript.yml",
"content": "name: \"TypeScript\"\non: [pull_request]\njobs:\n typescript:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - uses: pnpm/action-setup@v2\n with:\n version: 10\n - name: Install dependencies\n run: pnpm install --frozen-lockfile --recursive\n - name: Build NPM package\n run: pnpm build\n - name: Run TypeScript\n run: pnpm tsc\n"
},
{
"path": ".github/workflows/vitest.yml",
"content": "name: \"Vitest\"\non: [pull_request]\njobs:\n unit-tests:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - uses: pnpm/action-setup@v2\n with:\n version: 10\n - name: Install dependencies\n run: pnpm install --frozen-lockfile --recursive\n - name: Build NPM packages\n run: pnpm run build\n - name: Run tests\n run: pnpm run test:ci\n"
},
{
"path": ".gitignore",
"content": "dist\ndocs\nnode_modules\n\n.DS_Store\n.cache\n*.log\n.parcel-cache\n.pnp.*"
},
{
"path": ".nvmrc",
"content": "18\n"
},
{
"path": ".prettierignore",
"content": "/dist\n/docs\n/generated\n/public\n/src/routes/examples\n"
},
{
"path": "CHANGELOG.md",
"content": "# CHANGELOG\n\nSee the [releases page](../../releases).\n"
},
{
"path": "CODE_OF_CONDUCT.md",
"content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participation in our\ncommunity a harassment-free experience for everyone, regardless of age, body\nsize, visible or invisible disability, ethnicity, sex characteristics, gender\nidentity and expression, level of experience, education, socio-economic status,\nnationality, personal appearance, race, religion, or sexual identity and\norientation.\n\nWe pledge to act and interact in ways that contribute to an open, welcoming,\ndiverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our\ncommunity include:\n\n- Demonstrating empathy and kindness toward other people\n- Being respectful of differing opinions, viewpoints, and experiences\n- Giving and gracefully accepting constructive feedback\n- Accepting responsibility and apologizing to those affected by our mistakes,\n and learning from the experience\n- Focusing on what is best not just for us as individuals, but for the overall\n community\n\nExamples of unacceptable behavior include:\n\n- The use of sexualized language or imagery, and sexual attention or advances of\n any kind\n- Trolling, insulting or derogatory comments, and personal or political attacks\n- Public or private harassment\n- Publishing others' private information, such as a physical or email address,\n without their explicit permission\n- Other conduct which could reasonably be considered inappropriate in a\n professional setting\n\n## Enforcement Responsibilities\n\nCommunity leaders are responsible for clarifying and enforcing our standards of\nacceptable behavior and will take appropriate and fair corrective action in\nresponse to any behavior that they deem inappropriate, threatening, offensive,\nor harmful.\n\nCommunity leaders have the right and responsibility to remove, edit, or reject\ncomments, commits, code, wiki edits, issues, and other contributions that are\nnot aligned to this Code of Conduct, and will communicate reasons for moderation\ndecisions when appropriate.\n\n## Scope\n\nThis Code of Conduct applies within all community spaces, and also applies when\nan individual is officially representing the community in public spaces.\nExamples of representing our community include using an official e-mail address,\nposting via an official social media account, or acting as an appointed\nrepresentative at an online or offline event.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be\nreported to the community leaders responsible for enforcement at\nme+coc@kentcdodds.com. All complaints will be reviewed and investigated promptly\nand fairly.\n\nAll community leaders are obligated to respect the privacy and security of the\nreporter of any incident.\n\n## Enforcement Guidelines\n\nCommunity leaders will follow these Community Impact Guidelines in determining\nthe consequences for any action they deem in violation of this Code of Conduct:\n\n### 1. Correction\n\n**Community Impact**: Use of inappropriate language or other behavior deemed\nunprofessional or unwelcome in the community.\n\n**Consequence**: A private, written warning from community leaders, providing\nclarity around the nature of the violation and an explanation of why the\nbehavior was inappropriate. A public apology may be requested.\n\n### 2. Warning\n\n**Community Impact**: A violation through a single incident or series of\nactions.\n\n**Consequence**: A warning with consequences for continued behavior. No\ninteraction with the people involved, including unsolicited interaction with\nthose enforcing the Code of Conduct, for a specified period of time. This\nincludes avoiding interactions in community spaces as well as external channels\nlike social media. Violating these terms may lead to a temporary or permanent\nban.\n\n### 3. Temporary Ban\n\n**Community Impact**: A serious violation of community standards, including\nsustained inappropriate behavior.\n\n**Consequence**: A temporary ban from any sort of interaction or public\ncommunication with the community for a specified period of time. No public or\nprivate interaction with the people involved, including unsolicited interaction\nwith those enforcing the Code of Conduct, is allowed during this period.\nViolating these terms may lead to a permanent ban.\n\n### 4. Permanent Ban\n\n**Community Impact**: Demonstrating a pattern of violation of community\nstandards, including sustained inappropriate behavior, harassment of an\nindividual, or aggression toward or disparagement of classes of individuals.\n\n**Consequence**: A permanent ban from any sort of public interaction within the\ncommunity.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage],\nversion 2.0, available at\nhttps://www.contributor-covenant.org/version/2/0/code_of_conduct.html.\n\nCommunity Impact Guidelines were inspired by\n[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).\n\n[homepage]: https://www.contributor-covenant.org\n\nFor answers to common questions about this code of conduct, see the FAQ at\nhttps://www.contributor-covenant.org/faq. Translations are available at\nhttps://www.contributor-covenant.org/translations.\n"
},
{
"path": "CONTRIBUTING.md",
"content": "# Contributing\n\nThanks for your interest in contributing to this project!\n\nHere are a couple of guidelines to keep in mind before opening a Pull Request:\n\n- Please open a GitHub issue for discussion _before_ submitting any significant changes to this API (including new features or functionality).\n- Please don't submit code that has been written by code-generation tools such as Copilot or Claude. (There's nothing wrong with these tools, but I'd prefer them not be a part of this project.)\n\n## Local development\n\nTo get started:\n```sh\npnpm install\n```\n\n### Running the documentation site locally\n\nThe documentation site is a great place to test pending changes. It runs on localhost port 3000 and can be started by running:\n```sh\npnpm dev \n```\n\n### Running tests locally\n\nTo run unit tests locally:\n```sh\npnpm test\n```\n\n### Updating assets\n\nBefore submitting, also make sure to update generated docs/examples:\n```\npnpm compile\npnpm prettier\npnpm lint\n```\n\n> [!NOTE]\n> If you forget this step, CI will remind you!"
},
{
"path": "LICENSE",
"content": "The MIT License (MIT)\nCopyright (c) 2020 Brian Vaughn\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "\n\n`react-error-boundary`: Reusable React [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) component. Supports all React renderers (including React DOM and React Native).\n\n### If you like this project, š [become a sponsor](https://github.com/sponsors/bvaughn/) or ā [buy me a coffee](http://givebrian.coffee/)\n\n## Getting started\n\n```sh\n# npm\nnpm install react-error-boundary\n\n# pnpm\npnpm add react-error-boundary\n\n# yarn\nyarn add react-error-boundary\n```\n\n## FAQs\n\nFrequently asked questions can be found [here](https://react-error-boundary-lib.vercel.app/common-questions).\n\n## API\n\n### ErrorBoundary\n\n\nA reusable React [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n\nThis package is built on top of React [error boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary),\nso it has all of the advantages and constraints of that API.\nThis means that it can't catch errors during:\n- Server side rendering\n- Event handlers\n- Asynchronous code (including effects)\n\nā¹ļø The component provides several ways to render a fallback: `fallback`, `fallbackRender`, and `FallbackComponent`.\nRefer to the documentation to determine which is best for your application.\n\nā¹ļø This is a **client component**. You can only pass props to it that are serializeable or use it in files that have a `\"use client\";` directive.\n\n\n#### Required props\n\n\nNone\n\n\n#### Optional props\n\n\n\n
\n \n
\n
Name
\n
Description
\n
\n \n \n
\n
onError
\n
Optional callback to enable e.g. logging error information to a server.\n@param error Value that was thrown; typically an instance of Error\n@param info React "component stack" identifying where the error was thrown
\n
\n
\n
\n
onReset
\n
Optional callback to to be notified when an error boundary is "reset" so React can retry the failed render.
\n
\n
\n
\n
resetKeys
\n
When changed, these keys will reset a triggered error boundary.\nThis can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\nSee the the documentation for examples of how to use this prop.
\n
\n
\n
\n
fallback
\n
Static content to render in place of an error if one is thrown.
\n
<ErrorBoundary fallback={<div className="text-red">Something went wrong</div>} />\n
\n
\n
\n
\n
FallbackComponent
\n
React component responsible for returning a fallback UI based on a thrown value.
\n
<ErrorBoundary FallbackComponent={Fallback} />\n
\n
\n
\n
\n
fallbackRender
\n
Render prop function responsible for returning a fallback UI based on a thrown value.
;\n },\n );\n });\n\n it(\"should render fallback in the event of an error\", () => {\n shouldThrow = true;\n render();\n expect(getErrorMessage(lastRenderedError)).toBe(\"š„š„š„\");\n expect(fallbackRender).toHaveBeenCalled();\n expect(container.textContent).toBe(\"fallbackRender\");\n });\n\n it(\"should re-render children if boundary is reset via prop\", () => {\n shouldThrow = true;\n render();\n expect(getErrorMessage(lastRenderedError)).toBe(\"š„š„š„\");\n expect(fallbackRender).toHaveBeenCalled();\n expect(container.textContent).toBe(\"fallbackRender\");\n\n act(() => {\n shouldThrow = false;\n assert(lastRenderedResetErrorBoundary !== null);\n lastRenderedResetErrorBoundary();\n });\n\n expect(container.textContent).toBe(\"Content\");\n });\n\n it(\"should re-render children if boundary is reset reset keys\", () => {\n shouldThrow = true;\n render({ resetKeys: [1] });\n expect(getErrorMessage(lastRenderedError)).toBe(\"š„š„š„\");\n expect(fallbackRender).toHaveBeenCalled();\n expect(container.textContent).toBe(\"fallbackRender\");\n\n shouldThrow = false;\n render({ resetKeys: [2] });\n expect(container.textContent).toBe(\"Content\");\n });\n });\n\n describe(\"thrown values\", () => {\n let lastRenderedError: unknown | null = null;\n let fallbackRender: (props: FallbackProps) => ReactElement;\n let onError: Mock<(...args: unknown[]) => unknown>;\n\n beforeEach(() => {\n lastRenderedError = null;\n\n onError = vi.fn();\n\n fallbackRender = ({ error }: FallbackProps) => {\n lastRenderedError = error;\n\n return
Error
;\n };\n });\n\n function render() {\n act(() => {\n root.render(\n \n Content\n ,\n );\n });\n }\n\n it(\"should support thrown strings\", () => {\n shouldThrow = true;\n valueToThrow = \"String error\";\n\n render();\n\n expect(lastRenderedError).toBe(\"String error\");\n expect(onError).toHaveBeenCalledTimes(1);\n expect(onError.mock.calls[0][0]).toEqual(\"String error\");\n expect(container.textContent).toBe(\"Error\");\n });\n\n it(\"should support thrown null or undefined values\", () => {\n shouldThrow = true;\n valueToThrow = null;\n\n render();\n\n expect(lastRenderedError).toBe(null);\n expect(onError).toHaveBeenCalledTimes(1);\n expect(onError.mock.calls[0][0]).toEqual(null);\n expect(container.textContent).toBe(\"Error\");\n });\n });\n\n // TODO Various cases with resetKeys changing (length, order, etc)\n // TODO Errors thrown again after reset are caught\n // TODO Nested error boundaries if a fallback throws\n});\n"
},
{
"path": "lib/components/ErrorBoundary.tsx",
"content": "import { Component, createElement, type ErrorInfo } from \"react\";\nimport { ErrorBoundaryContext } from \"../context/ErrorBoundaryContext\";\nimport type { ErrorBoundaryProps, FallbackProps } from \"../types\";\n\nconst isDevelopment = import.meta.env.DEV;\n\ntype ErrorBoundaryState =\n | {\n didCatch: true;\n error: unknown;\n }\n | {\n didCatch: false;\n error: null;\n };\n\nconst initialState: ErrorBoundaryState = {\n didCatch: false,\n error: null,\n};\n\n/**\n * A reusable React [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) component.\n * Wrap this component around other React components to \"catch\" errors and render a fallback UI.\n *\n * This package is built on top of React [error boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary),\n * so it has all of the advantages and constraints of that API.\n * This means that it can't catch errors during:\n * - Server side rendering\n * - Event handlers\n * - Asynchronous code (including effects)\n *\n * ā¹ļø The component provides several ways to render a fallback: `fallback`, `fallbackRender`, and `FallbackComponent`.\n * Refer to the documentation to determine which is best for your application.\n *\n * ā¹ļø This is a **client component**. You can only pass props to it that are serializeable or use it in files that have a `\"use client\";` directive.\n */\nexport class ErrorBoundary extends Component<\n ErrorBoundaryProps,\n ErrorBoundaryState\n> {\n constructor(props: ErrorBoundaryProps) {\n super(props);\n\n this.resetErrorBoundary = this.resetErrorBoundary.bind(this);\n this.state = initialState;\n }\n\n static getDerivedStateFromError(error: Error) {\n return { didCatch: true, error };\n }\n\n resetErrorBoundary(...args: unknown[]) {\n const { error } = this.state;\n\n if (error !== null) {\n this.props.onReset?.({\n args,\n reason: \"imperative-api\",\n });\n\n this.setState(initialState);\n }\n }\n\n componentDidCatch(error: unknown, info: ErrorInfo) {\n this.props.onError?.(error, info);\n }\n\n componentDidUpdate(\n prevProps: ErrorBoundaryProps,\n prevState: ErrorBoundaryState,\n ) {\n const { didCatch } = this.state;\n const { resetKeys } = this.props;\n\n // There's an edge case where if the thing that triggered the error happens to *also* be in the resetKeys array,\n // we'd end up resetting the error boundary immediately.\n // This would likely trigger a second error to be thrown.\n // So we make sure that we don't check the resetKeys on the first call of cDU after the error is set.\n\n if (\n didCatch &&\n prevState.error !== null &&\n hasArrayChanged(prevProps.resetKeys, resetKeys)\n ) {\n this.props.onReset?.({\n next: resetKeys,\n prev: prevProps.resetKeys,\n reason: \"keys\",\n });\n\n this.setState(initialState);\n }\n }\n\n render() {\n const { children, fallbackRender, FallbackComponent, fallback } =\n this.props;\n const { didCatch, error } = this.state;\n\n let childToRender = children;\n\n if (didCatch) {\n const props: FallbackProps = {\n error,\n resetErrorBoundary: this.resetErrorBoundary,\n };\n\n if (typeof fallbackRender === \"function\") {\n childToRender = fallbackRender(props);\n } else if (FallbackComponent) {\n childToRender = createElement(FallbackComponent, props);\n } else if (fallback !== undefined) {\n childToRender = fallback;\n } else {\n if (isDevelopment) {\n console.error(\n \"react-error-boundary requires either a fallback, fallbackRender, or FallbackComponent prop\",\n );\n }\n\n throw error;\n }\n }\n\n return createElement(\n ErrorBoundaryContext.Provider,\n {\n value: {\n didCatch,\n error,\n resetErrorBoundary: this.resetErrorBoundary,\n },\n },\n childToRender,\n );\n }\n}\n\nfunction hasArrayChanged(a: unknown[] = [], b: unknown[] = []) {\n return (\n a.length !== b.length || a.some((item, index) => !Object.is(item, b[index]))\n );\n}\n"
},
{
"path": "lib/context/ErrorBoundaryContext.ts",
"content": "import { createContext } from \"react\";\n\nexport type ErrorBoundaryContextType = {\n didCatch: boolean;\n error: unknown | null;\n resetErrorBoundary: (...args: unknown[]) => void;\n};\n\nexport const ErrorBoundaryContext =\n createContext(null);\n"
},
{
"path": "lib/hooks/useErrorBoundary.test.tsx",
"content": "import { act, useLayoutEffect, type ReactNode } from \"react\";\nimport { createRoot } from \"react-dom/client\";\nimport { beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { ErrorBoundary } from \"../components/ErrorBoundary\";\nimport { assert } from \"../utils/assert\";\nimport { getErrorMessage } from \"../utils/getErrorMessage\";\nimport { useErrorBoundary, type UseErrorBoundaryApi } from \"./useErrorBoundary\";\n\ndescribe(\"useErrorBoundary\", () => {\n let container: HTMLDivElement;\n\n beforeEach(() => {\n vi.spyOn(console, \"error\").mockImplementation(() => {\n // Don't clutter the console with expected error text\n });\n\n container = document.createElement(\"div\");\n });\n\n function render(content: ReactNode) {\n const root = createRoot(container);\n act(() => {\n root.render(content);\n });\n return root;\n }\n\n it(\"should activate and deactivate the nearest error boundary\", () => {\n let resetBoundaryFn: UseErrorBoundaryApi[\"resetBoundary\"] | null = null;\n let showBoundaryFn: UseErrorBoundaryApi[\"showBoundary\"] | null = null;\n\n function Child() {\n const { resetBoundary, showBoundary } = useErrorBoundary();\n\n useLayoutEffect(() => {\n resetBoundaryFn = resetBoundary;\n showBoundaryFn = showBoundary;\n }, [resetBoundary, showBoundary]);\n\n return
Child
;\n }\n\n render(\n (\n
Fallback: {getErrorMessage(error)}
\n )}\n >\n \n ,\n );\n expect(container.textContent).toBe(\"Child\");\n\n act(() => {\n assert(showBoundaryFn != null);\n showBoundaryFn(new Error(\"Example\"));\n });\n expect(container.textContent).toBe(\"Fallback: Example\");\n\n act(() => {\n assert(resetBoundaryFn != null);\n resetBoundaryFn();\n });\n expect(container.textContent).toBe(\"Child\");\n });\n\n it(\"should expose the current error to a fallback component\", () => {\n const errorToThrow = new Error(\"Thrown\");\n\n function Child() {\n const { error } = useErrorBoundary();\n expect(error).toBe(null);\n\n throw errorToThrow;\n\n return null;\n }\n\n function Fallback() {\n const { error } = useErrorBoundary();\n expect(error).toBe(errorToThrow);\n\n return \"Fallback\";\n }\n\n render(\n \n \n ,\n );\n\n expect(container.textContent).toBe(\"Fallback\");\n });\n});\n"
},
{
"path": "lib/hooks/useErrorBoundary.ts",
"content": "import { useContext, useMemo, useState } from \"react\";\nimport { ErrorBoundaryContext } from \"../context/ErrorBoundaryContext\";\nimport { assertErrorBoundaryContext } from \"../utils/assertErrorBoundaryContext\";\n\ntype UseErrorBoundaryState =\n | { error: unknown; hasError: true }\n | { error: null; hasError: false };\n\nexport type UseErrorBoundaryApi = {\n error: unknown | null;\n resetBoundary: () => void;\n showBoundary: (error: unknown) => void;\n};\n\n/**\n * Convenience hook for imperatively showing or dismissing error boundaries.\n *\n * ā ļø This hook must only be used within an `ErrorBoundary` subtree.\n */\nexport function useErrorBoundary(): {\n /**\n * The currently visible `Error` (if one has been thrown).\n */\n error: unknown | null;\n\n /**\n * Method to reset and retry the nearest active error boundary (if one is active).\n */\n resetBoundary: () => void;\n\n /**\n * Trigger the nearest error boundary to display the error provided.\n *\n * ā¹ļø React only handles errors thrown during render or during component lifecycle methods (e.g. effects and did-mount/did-update).\n * Errors thrown in event handlers, or after async code has run, will not be caught.\n * This method is a way to imperatively trigger an error boundary during these phases.\n */\n showBoundary: (error: unknown) => void;\n} {\n const context = useContext(ErrorBoundaryContext);\n\n assertErrorBoundaryContext(context);\n\n const { error, resetErrorBoundary } = context;\n\n const [state, setState] = useState({\n error: null,\n hasError: false,\n });\n\n const memoized = useMemo(\n () => ({\n error,\n resetBoundary: () => {\n resetErrorBoundary();\n setState({ error: null, hasError: false });\n },\n showBoundary: (error: unknown) =>\n setState({\n error,\n hasError: true,\n }),\n }),\n [error, resetErrorBoundary],\n );\n\n if (state.hasError) {\n throw state.error;\n }\n\n return memoized;\n}\n"
},
{
"path": "lib/index.ts",
"content": "\"use client\";\n\nexport { ErrorBoundary } from \"./components/ErrorBoundary\";\nexport { ErrorBoundaryContext } from \"./context/ErrorBoundaryContext\";\nexport { useErrorBoundary } from \"./hooks/useErrorBoundary\";\nexport { getErrorMessage } from \"./utils/getErrorMessage\";\nexport { withErrorBoundary } from \"./utils/withErrorBoundary\";\n\nexport type { ErrorBoundaryContextType } from \"./context/ErrorBoundaryContext\";\nexport type { UseErrorBoundaryApi } from \"./hooks/useErrorBoundary\";\nexport type {\n ErrorBoundaryProps,\n ErrorBoundaryPropsWithComponent,\n ErrorBoundaryPropsWithFallback,\n ErrorBoundaryPropsWithRender,\n FallbackProps,\n OnErrorCallback,\n} from \"./types\";\n"
},
{
"path": "lib/types.ts",
"content": "import type {\n ComponentType,\n ErrorInfo,\n PropsWithChildren,\n ReactNode,\n} from \"react\";\n\nexport type FallbackProps = {\n error: unknown;\n resetErrorBoundary: (...args: unknown[]) => void;\n};\n\nexport type OnErrorCallback = (error: unknown, info: ErrorInfo) => void;\n\ntype ErrorBoundarySharedProps = PropsWithChildren<{\n /**\n * Optional callback to enable e.g. logging error information to a server.\n *\n * @param error Value that was thrown; typically an instance of `Error`\n * @param info React \"component stack\" identifying where the error was thrown\n */\n onError?: (error: unknown, info: ErrorInfo) => void;\n\n /**\n * Optional callback to to be notified when an error boundary is \"reset\" so React can retry the failed render.\n */\n onReset?: (\n details:\n | { reason: \"imperative-api\"; args: unknown[] }\n | {\n reason: \"keys\";\n prev: unknown[] | undefined;\n next: unknown[] | undefined;\n },\n ) => void;\n\n /**\n * When changed, these keys will reset a triggered error boundary.\n * This can be useful when an error condition may be tied to some specific state (that can be uniquely identified by key).\n * See the the documentation for examples of how to use this prop.\n */\n resetKeys?: unknown[];\n}>;\n\nexport type ErrorBoundaryPropsWithComponent = ErrorBoundarySharedProps & {\n fallback?: never;\n /**\n * React component responsible for returning a fallback UI based on a thrown value.\n *\n * ```tsx\n * \n * ```\n */\n FallbackComponent: ComponentType;\n fallbackRender?: never;\n};\n\nexport type ErrorBoundaryPropsWithRender = ErrorBoundarySharedProps & {\n fallback?: never;\n FallbackComponent?: never;\n /**\n * [Render prop](https://react.dev/reference/react/Children#calling-a-render-prop-to-customize-rendering) function responsible for returning a fallback UI based on a thrown value.\n *\n * ```tsx\n *
...
} />\n * ```\n */\n fallbackRender: (props: FallbackProps) => ReactNode;\n};\n\nexport type ErrorBoundaryPropsWithFallback = ErrorBoundarySharedProps & {\n /**\n * Static content to render in place of an error if one is thrown.\n *\n * ```tsx\n * Something went wrong} />\n * ```\n */\n fallback: ReactNode;\n FallbackComponent?: never;\n fallbackRender?: never;\n};\n\nexport type ErrorBoundaryProps =\n | ErrorBoundaryPropsWithFallback\n | ErrorBoundaryPropsWithComponent\n | ErrorBoundaryPropsWithRender;\n"
},
{
"path": "lib/utils/assert.ts",
"content": "export function assert(\n expectedCondition: unknown,\n message: string = \"Assertion error\",\n): asserts expectedCondition {\n if (!expectedCondition) {\n throw Error(message);\n }\n}\n"
},
{
"path": "lib/utils/assertErrorBoundaryContext.ts",
"content": "import type { ErrorBoundaryContextType } from \"../context/ErrorBoundaryContext\";\nimport { isErrorBoundaryContext } from \"./isErrorBoundaryContext\";\n\nexport function assertErrorBoundaryContext(\n value: unknown,\n): asserts value is ErrorBoundaryContextType {\n if (!isErrorBoundaryContext(value)) {\n throw new Error(\"ErrorBoundaryContext not found\");\n }\n}\n"
},
{
"path": "lib/utils/getErrorMessage.ts",
"content": "export function getErrorMessage(thrown: unknown): string | undefined {\n switch (typeof thrown) {\n case \"object\": {\n if (\n thrown !== null &&\n \"message\" in thrown &&\n typeof thrown.message === \"string\"\n ) {\n return thrown.message;\n }\n break;\n }\n case \"string\": {\n return thrown;\n }\n }\n}\n"
},
{
"path": "lib/utils/isErrorBoundaryContext.ts",
"content": "import type { ErrorBoundaryContextType } from \"../context/ErrorBoundaryContext\";\n\nexport function isErrorBoundaryContext(\n value: unknown,\n): value is ErrorBoundaryContextType {\n return (\n value !== null &&\n typeof value === \"object\" &&\n \"didCatch\" in value &&\n typeof value.didCatch === \"boolean\" &&\n \"error\" in value &&\n \"resetErrorBoundary\" in value &&\n typeof value.resetErrorBoundary === \"function\"\n );\n}\n"
},
{
"path": "lib/utils/withErrorBoundary.test.tsx",
"content": "import { Component, createRef, type PropsWithChildren } from \"react\";\nimport { createRoot } from \"react-dom/client\";\nimport { act } from \"react-dom/test-utils\";\nimport { beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { withErrorBoundary } from \"./withErrorBoundary\";\n\ndescribe(\"withErrorBoundary\", () => {\n let container: HTMLDivElement;\n let root: ReturnType;\n let shouldThrow = true;\n let valueToThrow: unknown;\n\n beforeEach(() => {\n // @ts-expect-error This is a React internal\n global.IS_REACT_ACT_ENVIRONMENT = true;\n\n // Don't clutter the console with expected error text\n vi.spyOn(console, \"error\").mockImplementation(() => {\n // No-op\n });\n\n container = document.createElement(\"div\");\n root = createRoot(container);\n shouldThrow = false;\n valueToThrow = new Error(\"š„š„š„\");\n });\n\n function MaybeThrows({ children = \"Children\" }: PropsWithChildren) {\n if (shouldThrow) {\n throw valueToThrow;\n }\n return children;\n }\n\n function render() {\n const ErrorBoundary = withErrorBoundary(MaybeThrows, {\n fallback:
Error
,\n });\n\n act(() => {\n root.render();\n });\n }\n\n it(\"should render children within the created HOC\", () => {\n render();\n expect(container.textContent).toBe(\"Children\");\n });\n\n it(\"should catch errors with the created HOC\", () => {\n shouldThrow = true;\n render();\n expect(container.textContent).toBe(\"Error\");\n });\n\n it(\"should forward refs\", () => {\n type Props = { foo: string };\n\n class Inner extends Component {\n test() {\n // No-op\n }\n render() {\n return this.props.foo;\n }\n }\n\n const Wrapped = withErrorBoundary(Inner, {\n fallback:
\n This package is built on top of React{\" \"}\n \n error boundaries\n \n , so it has all of the advantages and constraints of that API.\n
\n
This means that it can't catch errors during:
\n
\n
Server side rendering
\n
Event handlers
\n
Asynchronous code (including effects)
\n
\n
\n You can show an error boundary for asynchronous code, but you\n have to catch the error yourself.{\" \"}\n Learn more.\n
\n
\n);\n\nconst commonQuestions: CommonQuestion[] = [\n {\n id: \"uncaught-error\",\n question: \"Why didn't the boundary catch my error?\",\n answer: clientSideWarning,\n },\n {\n id: \"react-types-mismatch\",\n question: (\n <>\n ErrorBoundary cannot be used as a JSX component\n \n ),\n answer: (\n <>\n
\n This error can be caused by a version mismatch between{\" \"}\n react and @types/react. To fix this, ensure\n that both match exactly.\n
\n
\n For NPM, you may need to use an{\" \"}\n \n override\n \n :\n
\n \n
\n Yarn has a similar mechanism called a{\" \"}\n \n resolution\n \n :\n
\n \n \n ),\n },\n];\n"
},
{
"path": "src/components/ContinueLink.tsx",
"content": "import type { Path } from \"../routes\";\nimport { Link } from \"./Link\";\n\nexport function ContinueLink({ title, to }: { title: string; to: Path }) {\n return (\n
\n Continue to {title}ā¦\n
\n );\n}\n"
},
{
"path": "src/components/Divider.tsx",
"content": "export function Divider() {\n return ;\n}\n"
},
{
"path": "src/components/Link.tsx",
"content": "import type { HTMLAttributes } from \"react\";\nimport { Link as ExternalLink } from \"react-lib-tools\";\nimport type { Path } from \"../routes\";\n\nexport function Link({\n to,\n ...rest\n}: HTMLAttributes & {\n to: Path;\n}) {\n return ;\n}\n"
},
{
"path": "src/components/NavLink.tsx",
"content": "import { type PropsWithChildren } from \"react\";\nimport { NavLink as NavLinkExternal, type DefaultPath } from \"react-lib-tools\";\nimport { type Path } from \"../routes\";\n\nexport function NavLink({\n children,\n className,\n path,\n}: PropsWithChildren<{\n className?: string | undefined;\n path: Path | DefaultPath;\n}>) {\n return (\n \n );\n}\n"
},
{
"path": "src/routes/AsyncUserCodeErrorsRoute.tsx",
"content": "import { Box, Code, Header, Link } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/AsyncUserCodeErrors.json\";\n\nexport default function AsyncUserCodeErrorsRoute() {\n return (\n \n \n
\n React only handles errors thrown during render or during component\n lifecycle methods (e.g. effects and did-mount/did-update). Errors thrown\n in event handlers, or after async code has run, will not be caught.\n
\n
\n The useErrorBoundary hook\n can be used to pass those errors to the nearest error boundary:\n
\n \n \n );\n}\n"
},
{
"path": "src/routes/ErrorBoundaryPropsRoute.tsx",
"content": "import { Box, ComponentProps, type ComponentMetadata } from \"react-lib-tools\";\nimport json from \"../../public/generated/docs/ErrorBoundary.json\";\n\nexport default function ErrorBoundaryPropsRoute() {\n return (\n \n \n \n );\n}\n"
},
{
"path": "src/routes/ErrorLoggingRoute.tsx",
"content": "import { Box, Code, Header } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/ErrorLogging.json\";\n\nexport default function ErrorLoggingRoute() {\n return (\n \n \n
\n Use the onError callback to log errors to a service like\n Sentry.\n
\n \n \n );\n}\n"
},
{
"path": "src/routes/FallbackComponentRoute.tsx",
"content": "import { Box, Code, Header } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/FallbackComponent.json\";\n\nexport default function FallbackComponentRoute() {\n return (\n \n \n
\n React component responsible for returning a fallback UI based on a\n thrown value.\n
\n \n \n );\n}\n"
},
{
"path": "src/routes/FallbackContentRoute.tsx",
"content": "import { Box, Code, Header } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/FallbackContent.json\";\n\nexport default function RenderPropRoute() {\n return (\n \n \n
The simplest way to render a default error message.
\n \n \n );\n}\n"
},
{
"path": "src/routes/GetErrorMessageRoute.tsx",
"content": "import { Box, Code, ExternalLink, Header } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/GetErrorMessage.json\";\n\nexport default function GetErrorMessageRoute() {\n return (\n \n \n
\n Typically thrown errors in JavaScript are instances of type{\" \"}\n Error, but{\" \"}\n \n this is not always the case\n \n . Any value can be thrown- strings, numbers, even null or{\" \"}\n undefined.\n
\n
\n To simplify working with thrown values, this library exports a utility\n method called getErrorMessage.\n
\n \n \n );\n}\n"
},
{
"path": "src/routes/RenderPropRoute.tsx",
"content": "import { Box, Code, ExternalLink, Header } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/RenderProp.json\";\n\nexport default function RenderPropRoute() {\n return (\n \n \n
\n \n Render prop\n {\" \"}\n function responsible for returning a fallback UI based on a thrown\n value.\n
\n \n \n );\n}\n"
},
{
"path": "src/routes/ResetNearestBoundaryRoute.tsx",
"content": "import { Box, Code, Header } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/ResetWithUseErrorBoundary.json\";\nimport { Link } from \"../components/Link\";\n\nexport default function ResetNearestBoundaryRoute() {\n return (\n \n \n
\n The useErrorBoundary hook\n can be used to reset the nearest error boundary and retry a failed\n render attempt.\n
\n \n \n );\n}\n"
},
{
"path": "src/routes/UseErrorBoundaryRoute.tsx",
"content": "import { Box, Callout, Code, Header } from \"react-lib-tools\";\nimport { html } from \"../../public/generated/examples/UseErrorBoundary.json\";\n\nexport default function UseErrorBoundaryRoute() {\n return (\n \n \n
\n Convenience hook for imperatively showing or dismissing error\n boundaries.\n
\n \n \n This hook must only be used within an ErrorBoundary{\" \"}\n subtree.\n \n \n );\n}\n"
},
{
"path": "src/routes/WithErrorBoundaryRoute.tsx",
"content": "import { Box, Code, ExternalLink, Header } from \"react-lib-tools\";\nimport { html as htmlA } from \"../../public/generated/examples/WithErrorBoundaryA.json\";\nimport { html as htmlB } from \"../../public/generated/examples/WithErrorBoundaryB.json\";\nimport { html as htmlC } from \"../../public/generated/examples/WithErrorBoundaryC.json\";\n\nexport default function WithErrorBoundaryRoute() {\n return (\n \n \n
\n This package can also be used as a{\" \"}\n \n higher-order component\n \n . For example, given a component like this:\n
\n \n
\n You could use the withErrorBoundary HOC to create a wrapper\n component:\n
\n \n
And then render it like this
\n \n
\n This might be useful for certain types of reusable/library components.\n
\n \n );\n}\n"
},
{
"path": "src/routes/examples/AsyncUserCodeErrors.tsx",
"content": "import { useEffect } from \"react\"; // hidden\nimport { useErrorBoundary } from \"react-error-boundary\";\n\nfunction useUserProfileInfo({ username }: { username: string }) {\n const { showBoundary } = useErrorBoundary();\n\n useEffect(() => {\n fetchGreeting(username).then(\n (response) => {\n // Set data in state and re-render ...\n response; // hidden\n },\n (error) => {\n // Show error boundary\n showBoundary(error);\n }\n );\n });\n}\n\n// \n\nexport { useUserProfileInfo };\n\nasync function fetchGreeting(_: string) {}\n"
},
{
"path": "src/routes/examples/ErrorLogging.tsx",
"content": "import type { ErrorInfo } from \"react\";\nimport { ErrorBoundary } from \"react-error-boundary\";\n\nfunction logError(error: unknown, info: ErrorInfo) {\n // Do something with the error, e.g. log to an external API\n error; // hidden\n info; // hidden\n}\n\n\n \n;\n\n// \n\nfunction ErrorFallback() {\n return null;\n}\n\nfunction YourApplication() {\n return null;\n}\n"
},
{
"path": "src/routes/examples/FallbackComponent.tsx",
"content": "import { ErrorBoundary, getErrorMessage, type FallbackProps } from \"react-error-boundary\";\n\nfunction Fallback({ error, resetErrorBoundary }: FallbackProps) {\n return (\n
\n
Something went wrong:
\n
{getErrorMessage(error)}
\n \n
\n );\n}\n\n {\n // Reset the state of your app so the error doesn't happen again\n details; // hidden\n }}\n>\n \n;\n\n// \n\nfunction YourApplication() {\n return null;\n}\n"
},
{
"path": "src/routes/examples/FallbackContent.tsx",
"content": "import { ErrorBoundary } from \"react-error-boundary\";\n\nSomething went wrong}>\n \n;\n\n// \n\nfunction YourApplication() {\n return null;\n}\n"
},
{
"path": "src/routes/examples/GetErrorMessage.ts",
"content": "import { getErrorMessage, type FallbackProps } from \"react-error-boundary\";\n\nfunction Fallback({ error }: FallbackProps) {\n // Because 'error' can be anything, it's safest not to assume it's an Error\n // Use the getErrorMessage helper method to extract the message instead.\n const message = getErrorMessage(error) ?? \"Unknown error\";\n\n // Render fallback UI...\n return message; // hidden\n}\n\n// \n\nexport { Fallback };\n"
},
{
"path": "src/routes/examples/NpmResolution.json",
"content": "{\n \"overrides\": {\n \"@types/react\": \"17.0.60\"\n }\n}"
},
{
"path": "src/routes/examples/RenderProp.tsx",
"content": "import { ErrorBoundary, getErrorMessage } from \"react-error-boundary\";\n\n (\n
\n
Something went wrong:
\n
{getErrorMessage(error)}
\n \n
\n )}\n onReset={(details) => {\n // Reset the state of your app so the error doesn't happen again\n details; // hidden\n }}\n>\n \n;\n\n// \n\nfunction YourApplication() {\n return null;\n}\n"
},
{
"path": "src/routes/examples/ResetWithUseErrorBoundary.tsx",
"content": "import { useErrorBoundary } from \"react-error-boundary\";\n\nfunction Example() {\n const { resetBoundary } = useErrorBoundary();\n\n // Call resetBoundary() to reset the nearest ErrorBoundary and retry a failed render\n resetBoundary; // hidden\n}\n\n// \n\nexport { Example };\n"
},
{
"path": "src/routes/examples/UseClient.ts",
"content": "\"use client\";\n\n// Imports and components code go here..."
},
{
"path": "src/routes/examples/UseErrorBoundary.tsx",
"content": "import { useErrorBoundary } from \"react-error-boundary\";\n\nfunction Example() {\n const {\n // The currently visible Error (if one has been thrown).\n error,\n\n // Method to reset and retry the nearest active error boundary (if one is active).\n resetBoundary,\n\n // Trigger the nearest error boundary to display the error provided.\n showBoundary,\n } = useErrorBoundary();\n\n // ...\n error; // hidden\n resetBoundary; // hidden\n showBoundary; // hidden\n}\n\n// \n\nexport { Example };\n"
},
{
"path": "src/routes/examples/WithErrorBoundaryA.tsx",
"content": "function UserProfile({ username }: { username: string }) {\n username; // hidden\n return null; // hidden\n // Render...\n}\n\n// \n\nexport { UserProfile };\n"
},
{
"path": "src/routes/examples/WithErrorBoundaryB.tsx",
"content": "import { UserProfile } from \"./WithErrorBoundaryA\";\n\n// \n\nimport { withErrorBoundary } from \"react-error-boundary\";\n\nconst UserProfileWithErrorBoundary = withErrorBoundary(UserProfile, {\n fallback:
![\"react-error-boundary](\"https://react-error-boundary-lib.vercel.app/og.png\")
\n\n`react-error-boundary`: Reusable React [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) component. Supports all React renderers (including React DOM and React Native).\n\n### If you like this project, š [become a sponsor](https://github.com/sponsors/bvaughn/) or ā [buy me a coffee](http://givebrian.coffee/)\n\n## Getting started\n\n```sh\n# npm\nnpm install react-error-boundary\n\n# pnpm\npnpm add react-error-boundary\n\n# yarn\nyarn add react-error-boundary\n```\n\n## FAQs\n\nFrequently asked questions can be found [here](https://react-error-boundary-lib.vercel.app/common-questions).\n\n## API\n\n### ErrorBoundary\n\n\nA reusable React [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) component.\nWrap this component around other React components to \"catch\" errors and render a fallback UI.\n\nThis package is built on top of React [error boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary),\nso it has all of the advantages and constraints of that API.\nThis means that it can't catch errors during:\n- Server side rendering\n- Event handlers\n- Asynchronous code (including effects)\n\nā¹ļø The component provides several ways to render a fallback: `fallback`, `fallbackRender`, and `FallbackComponent`.\nRefer to the documentation to determine which is best for your application.\n\nā¹ļø This is a **client component**. You can only pass props to it that are serializeable or use it in files that have a `\"use client\";` directive.\n\n\n#### Required props\n\n\nNone\n\n\n#### Optional props\n\n\n\n