Error Boundary — o que é, componente React Native e tratamento de erros

O que é Error Boundary

Error Boundary é um mecanismo do React para degradação suave durante erros de renderização. Introduzido no React 16 (2017) como um componente wrapper que implementa um dos dois métodos do ciclo de vida: static getDerivedStateFromError ou componentDidCatch. O Error Boundary permite mostrar ao usuário uma mensagem significativa em vez de uma tela branca vazia ou uma falha completa do aplicativo.

Como o Error Boundary surgiu

Antes do React 16, qualquer erro não tratado no render causava uma falha completa do aplicativo com desmontagem de toda a árvore DOM. Em aplicativos web, isso significava uma tela branca vazia; no React Native, uma falha completa com retorno à Tela Inicial. A equipe do React introduziu o Error Boundary como um análogo de bloco catch para UI declarativa, pegando emprestado o conceito da abordagem “let it crash” da linguagem Erlang.

Importância para o React Native

No React Native, a ausência do Error Boundary significa uma falha completa do aplicativo em qualquer erro de renderização. O usuário perde toda a sua sessão atual sem opções de recuperação. O Error Boundary no React Native é criticamente importante porque os aplicativos móveis não podem ser recarregados como páginas da web — a sessão do usuário é irremediavelmente perdida, e o usuário tem que começar tudo do zero.

Como o Error Boundary funciona no React Native

Error Boundary funciona no nível da árvore React. Quando um componente filho lança um erro no render ou no ciclo de vida, o React não desmonta toda a árvore, mas passa o controle para o Error Boundary mais próximo na hierarquia. O Boundary chama getDerivedStateFromError, define state.hasError = true e renderiza a interface alternativa em vez do ramo de componentes quebrado.

import React, { Component, ErrorInfo, ReactNode } from "react"

interface Props {
    children: ReactNode
    fallback?: ReactNode
}

interface State {
    hasError: boolean
    error?: Error
}

class ErrorBoundary extends Component<Props, State> {
    constructor(props: Props) {
        super(props)
        this.state = { hasError: false }
    }

    static getDerivedStateFromError(error: Error): State {
        return { hasError: true, error }
    }

    componentDidCatch(error: Error, info: ErrorInfo) {
        console.error("Caught by boundary:", error)
        Crashlytics.recordException(error)
    }

    render() {
        if (this.state.hasError) {
            return this.props.fallback || <FallbackUI />
        }
        return this.props.children
    }
}

getDerivedStateFromError define o estado para renderizar a interface alternativa — é um método estático chamado durante a fase de renderização antes de confirmar as alterações. componentDidCatch é executado na fase de confirmação e é destinado a efeitos colaterais: registro, envio de relatórios de falha para o Crashlytics, análise. Os dois métodos separam a responsabilidade entre o gerenciamento do estado da UI e os efeitos colaterais.

Criação do componente Error Boundary

Para criar um Error Boundary, você precisa implementar um componente de classe com os métodos getDerivedStateFromError e/ou componentDidCatch. Componentes funcionais não podem ser Error Boundary — o React suporta essa funcionalidade apenas para componentes de classe porque o acesso aos métodos do ciclo de vida é necessário. A biblioteca react-error-boundary fornece uma implementação pronta com uma API baseada em hooks para maior conveniência.

// Exemplo de uso do Error Boundary no React Native
import { ErrorBoundary } from "react-error-boundary"

const FallbackComponent = ({ error, resetError }: FallbackProps) => (
    <View style={styles.container}>
        <Text>Algo deu errado</Text>
        <Text>{error.message}</Text>
        <Button title="Tentar novamente" onPress={resetError} />
    </View>
)

const App = () => (
    <SafeAreaView>
        <ErrorBoundary FallbackComponent={<FallbackComponent />}>
            <UserProfile userId={"123"} />
        </ErrorBoundary>
        <BottomNavigation />
    </SafeAreaView>
)

Níveis de encapsulamento — o Error Boundary pode ser colocado em diferentes níveis da hierarquia. Um Boundary global na raiz do aplicativo mostrará a interface alternativa em qualquer erro, mas a navegação ainda será preservada. Vários Boundaries no nível da tela permitem isolar erros: se uma tela quebrar, as demais continuam funcionando independentemente. O react-error-boundary simplifica o mecanismo de redefinição através do hook useErrorBoundary, permitindo redefinir o estado sem recarregar. Para projetos típicos, um esquema de três níveis de Boundary é considerado ideal para aplicativos React Native.

Redefinição do estado do Error Boundary

Após a ocorrência de um erro, o usuário pode clicar no botão “Tentar novamente”, que redefine hasError para false e renderiza novamente a árvore filha. O mecanismo de redefinição é importante para restaurar a funcionalidade do aplicativo sem recarregar. No react-error-boundary, o callback onReset é usado, que pode limpar o cache, buscar dados novamente ou atualizar o estado em níveis superiores da árvore.

Limitações do Error Boundary

Error Boundary não captura erros assíncronos — erros em setTimeout, setInterval, Promise, async/await. O React não pode interceptar erros fora do ciclo de renderização e hooks do ciclo de vida porque eles são executados em contextos de execução diferentes. Para erros assíncronos, é necessário um try-catch separado nos manipuladores ou um manipulador global de eventos unhandledrejection.

Manipuladores de eventos

Erros em onClick, onChange e outros manipuladores de eventos não são capturados pelo Error Boundary porque são executados fora da renderização do React. O tratamento de erros para manipuladores de eventos deve estar dentro do próprio manipulador usando try-catch. A biblioteca react-error-boundary fornece o hook useErrorHandler para lançar erros de manipuladores de eventos para o Boundary mais próximo.

Renderização do lado do servidor e Next.js

Error Boundary não funciona no lado do servidor no Next.js ou Gatsby. Os métodos getDerivedStateFromError e componentDidCatch não são chamados durante SSR porque os métodos do ciclo de vida estão disponíveis apenas no navegador. Para erros do servidor, é necessária uma estratégia separada: try-catch no getServerSideProps, páginas de fallback error.js (Next.js 13+), ou middleware global.

Camada nativa do React Native

No React Native, o Error Boundary não impede falhas no nível dos módulos nativos. Uma falha nativa (segfault, out-of-memory, exceção nativa) ocorre no nível do Objective-C ou Java e não atinge a camada JavaScript. Para falhas nativas, é necessário Crashlytics NDK (Android) ou KSCrash (iOS). O Error Boundary protege apenas a camada JavaScript de um aplicativo React Native.

Melhores práticas do Error Boundary

Coloque o Error Boundary nos limites dos módulos lógicos: um Boundary por tela, um por widget de terceiros, um por formulário complexo. Isso isola os erros e permite que o usuário continue trabalhando em outras partes do aplicativo. Um Boundary raiz deve estar sempre presente — para erros críticos em componentes comuns de navegação ou provedores. Cada Boundary é responsável pelo seu próprio fragmento de interface e não afeta os componentes vizinhos quando ocorre um erro.

Registro e monitoramento

Sempre passe o erro para o Crashlytics ou Sentry através do componentDidCatch. Adicione contexto: nome da tela, userId, versão do aplicativo, parâmetros de navegação. No Sentry, breadcrumbs estão disponíveis — uma sequência de ações do usuário que levaram ao erro. Para analisar a frequência de erros não fatais, use os painéis do Crashlytics com agrupamento por issue.

Interface alternativa (Fallback UI)

Não use um fallback simples — crie uma interface significativa. Conjunto recomendado para React Native: mensagem de erro (amigável ao usuário, não técnica), um botão “Tentar novamente”, um link para suporte ou chat. Evite uma Visualização vazia — o usuário pensará que o aplicativo falhou completamente e o fechará. O fallback deve estar integrado ao design geral do aplicativo.

Testes do Error Boundary

Teste cada Error Boundary usando React Testing Library ou React Native Testing Library. Crie um componente gatilho que lance um erro ao renderizar e verifique se a interface alternativa é exibida. Para testes de integração, use storybook com diferentes estados do Error Boundary: normal, erro, estado após redefinição. O teste automatizado do Boundary garante que quando o componente mudar, a interface alternativa continue funcionando corretamente em produção. A cobertura de testes para cada Boundary deve ser um requisito obrigatório de revisão de código para projetos React Native.