react-app-error-boundary

Allows you to turn react-error-overlay in your react-app from a mandatory-thing-you-never-asked-for into a handy-opt-in-feature.

Inspired by this SO question.

Why ever need this?

See discussion under this answer.

In very short:

When developing error boundary components and styling/testing how they look, this is an extremely annoying feature. It slows down development and adds no value. You should allow developers to decide whether they want this feature turned on or not

Why not just disable overlay?

Meaning, you always can simply do this:

import { stopReportingRuntimeErrors } from "react-error-overlay"
stopReportingRuntimeErrors()

which will disable overlay once and for all.

Well, because overlay is handy for unexpected errors. It works great on it's own. But when you know for sure that in some specific place you don't need overlay (for example, you want error from API to be caught by error boundary, this is an expected flow) – you don't have options for that. All or nothing.

That's where this solution comes into play.

Demo

Here is a repo where you can see this package in action.

Installation

npm install --save react-app-error-boundary
# or
yarn add react-app-error-boundary

Usage

1. Set up error handler in entry point:

// src/index.jsx
import { setupReactAppOverlayErrorHandler } from 'react-app-error-boundary'

ReactDOM.render(...)

setupReactAppOverlayErrorHandler()

2. Wrap desired application part into <ErrorBoundary> component:

import { ErrorBoundary } from 'react-app-error-boundary'

<ErrorBoundary>
  <DangerousComponent />
</ErrorBoundary>

That's it. With this configuration, if <DangerousComponent /> will throw, you should observe following:

• error message, written in red, in place of broken component
• error log in console, starting with Following error has been caught by <ErrorBoundary> component...
• no react-error-overlay displayed!

Additional configuration

For general usage of ErrorBoundary component, see documentation in original repo. All original props are available here too. Other stuff from repo also is re-exported, so you may also use extra features like useErrorHandler hook.

setDefaultErrorBoundaryFallback(errorRenderer)

In difference from original ErrorBoundary, here you have a default FallbackComponent provided. So you don't need to specify it explicitly every time.

To customize default fallback, use setDefaultErrorBoundaryFallback method:

// src/index.jsx
import { setDefaultErrorBoundaryFallback } from 'react-app-error-boundary'

setDefaultErrorBoundaryFallback(({ error }) => (
  <MyBeautifulErrorRenderer>{error.message}</MyBeautifulErrorRenderer>
))

allowDevErrorOverlay

If for some reason you want react-error-overlay displayed as it does normally, you may allow it for particular ErrorBoundary:

<ErrorBoundary allowDevErrorOverlay>...</ErrorBoundary>

logCaughtErrors

By default, errors handled by ErrorBoundary will still be logged in console (only in development mode). If you want to absolutely suppress caught errors, you may set it for particular ErrorBoundary:

<ErrorBoundary logCaughtErrors={false}>...</ErrorBoundary>

setDefaultErrorBoundaryOptions(options)

Default behavior of ErrorBoundary can be changed globally:

import { setDefaultErrorBoundaryOptions } from 'react-app-error-boundary'

setDefaultErrorBoundaryOptions({
  logCaughtErrors: false,
  allowDevErrorOverlay: true,
})

craOverlaySelector

This is an emergency option, just in case if styles of react-error-overlay will change – so this package will fail to hide it – and patch won't be released for some reason.

With this, you'll be able to patch this issue yourself:

import { setupReactAppOverlayErrorHandler } from 'react-app-error-boundary'

setupReactAppOverlayErrorHandler({
  craOverlaySelector: 'any-css-selector-here'
})

How it works

In general, it's based on this answer.

It sets up a global error handler – to intercept uncaught errors before react-error-overlay does, and handle them in a special way.

And it provides customized ErrorBoundary component (based on react-error-boundary), which marks errors handled by it as caught, so our global handler can decide whether to show overlay.

Unfortunately, using event.stopImmediatePropagation() to prevent react-error-overlay from handling errors is not appropriate (see comment under the mentioned answer), because it breaks all error-boundaries too. So instead, to "disable" overlay we'll just hide it via display: none.

Credits

Big thanks to react-error-boundary for a super convenient error-boundaries api.

LICENSE

MIT