react-error-boundary

A robust error boundary library for Lua React.

Why react-error-boundary

By design, React unmounts the entire tree when it encounters an unhandled error. This leaves the application in an ususable state unless the user refreshes the application. In the context of a video game, the player would need to leave and rejoin the game. Error boundaries provide a way to recover from errors to greatly improve user experience.

Use cases

• Rendering fallback components upon errors (e.g., error screen)
• Reverting state to a known good state
• Retrying render with reverted state
• Logging errors in an external database

Installation

Wally

Add the latest version of react-error-boundary to your wally.toml (e.g., ReactErrorBoundary = "chriscerie/react-error-boundary@<version>")

Getting Started

Getting started with react-error-boundary is simple. First, create a fallback component.

local e = React.createElement

local Fallback: React.FC<ReactErrorBoundary.FallbackProps> = function(_props)
    return e("TextLabel", {
        AnchorPoint = Vector2.new(0.5, 0.5),
        Size = UDim2.fromScale(0.5, 0.5),
        Position = UDim2.fromScale(0.5, 0.5),
        Text = "An error was encountered!.",
    })
end

Next, in your app, wrap an ErrorBoundary where needed.

local App: React.FC<{}> = function(_props)
    return e(ReactErrorBoundary.ErrorBoundary, {
        FallbackComponent = Fallback,
    }, {
        ComponentThatMightError = e(ComponentThatMightError),
    })
end

Now when ComponentThatMightError or any of its descendant errors, the error boundary will catch it and render the fallback component. When an error is encountered somewhere in your app, the nearest ErrorBoundary will catch and handle it. You don't need to wrap every component in an ErrorBoundary. Consider the granularity of error boundaries and where it makes sense to display an error message or revert states.

This was a very basic example. In a real application, you might want the fallback component to render a "go back" button that reverts state, or you might want to do that immediately after encountering an error. More advanced usage is detailed in react-error-boundary's official documentation.

License

react-error-boundary is available under the MIT license. See LICENSE for details.