react-use-error-boundary
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    react-use-error-boundary

    A React error boundary hook for function components

    What is this? 🧐

    React 16 introduced Error Boundaries. As of React 17, there still is not an equivalent hook for function components.

    This library draws inspiration from Preact's useErrorBoundary and attempts to recreate a similar API.

    Installation & Usage 📦

    1. Add this package to your project:
      • yarn add react-use-error-boundary

    Just trying things out or want to skip the build step? Use the unpkg URL:

    <script src="https://unpkg.com/react-use-error-boundary/dist/index.production.js"></script>
    

    Examples 🚀

    Whenever the component or a child component throws an error you can use this hook to catch the error and display an error UI to the user.

    // error = The error that was caught or `undefined` if nothing errored.
    // resetError = Call this function to mark an error as resolved. It's
    //   up to your app to decide what that means and if it is possible
    //   to recover from errors.
    const [error, resetError] = useErrorBoundary();

    For application monitoring, it's often useful to notify a service of any errors. useErrorBoundary accepts an optional callback that will be invoked when an error is encountered.

    const [error] = useErrorBoundary((error) => callMyApi(error.message));

    A full example may look like this:

    import { withErrorBoundary, useErrorBoundary } from "react-use-error-boundary";
    
    const App = withErrorBoundary({ children }) => {
      const [error, resetError] = useErrorBoundary(
        error => callMyApi(error.message)
      );
    
      if (error) {
        return (
          <div>
            <p>{error.message}</p>
            <button onClick={resetError}>Try again</button>
          </div>
        );
      }
    
      return <div>{children}</div>
    };

    Note that in addition to the hook, the component must be wrapped with withErrorBoundary. This function wraps the component with an Error Boundary and a context provider. Alternatively, the <ErrorBoundaryContext> component from this library may be placed in your component tree, above each component using useErrorBoundary.

    This was done to avoid hooking into React internals, which would otherwise be required. The hope is that the eventual React hook solution will present a similar API, and users can easily migrate by removing the withErrorBoundary wrapper.

    For a full project example take a look at the examples directory.

    Known Limitations ⚠️

    Because React recreates the component tree from scratch after catching an error, the component using the useErrorBoundary hook is always remounted after an error is encountered. This means any state will be reinitialized: useState and useRef hooks will be reinitialized to their initial value and will not persist across caught errors. Any values that need to be preserved across error catching must be lifted into a parent component above the component wrapped in withErrorBoundary.

    Highlights

    🌲 Tree shakeable. Ships ES Modules.

    🎁 Zero run time dependencies

    🦶 Small footprint 673 B minified and gzipped

    🪐 Isomorphic / Universal -- safe to run in any JS context: the browser or on a server

    🛠 This library follows semantic versioning

    Contributing 👫

    PR's and issues welcomed! For more guidance check out CONTRIBUTING.md

    Licensing 📃

    See the project's MIT License.

    Install

    npm i react-use-error-boundary

    DownloadsWeekly Downloads

    787

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    9.1 kB

    Total Files

    8

    Last publish

    Collaborators

    • tatethurston