Diseño de límites de error efectivos en aplicaciones complejas
Estrategias de límites de error que capturan fallos con elegancia, ofrecen alternativas útiles, reportan diagnósticos accionables y contienen el daño.
Un solo error no controlado en el árbol de componentes de React puede tumbar toda la aplicación. Los usuarios ven una pantalla en blanco, los informes de error inundan tu monitorización y la solución puede ser tan trivial como una comprobación de nulos en un componente tooltip. Los límites de error evitan este fallo en cascada, pero la mayoría de las implementaciones son demasiado simplistas: un único límite en la raíz de la aplicación que muestra un mensaje genérico de "Something went wrong".
La colocación estratégica de límites convierte fallos catastróficos en degradaciones localizadas donde los usuarios aún pueden completar sus tareas.
El problema de la arquitectura de un único límite
La mayoría de las aplicaciones envuelven todo su árbol en un único límite de error y lo dan por terminado.
// ❌ Single boundary — all-or-nothing failure
function App() {
return (
<ErrorBoundary fallback={<FullPageError />}>
<Header />
<Sidebar />
<MainContent>
<Dashboard />
{/* One broken widget crashes the entire app */}
</MainContent>
<Footer />
</ErrorBoundary>
);
}
// A bug in any component shows FullPageError
// User loses all functionality// ✅ Strategic boundaries — localized failure containment
function App() {
return (
<AppErrorBoundary fallback={<FullPageError />}>
<Header />
<ErrorBoundary
fallback={<SidebarFallback />}
onError={reportError}
>
<Sidebar />
</ErrorBoundary>
<MainContent>
<ErrorBoundary
fallback={<DashboardFallback />}
onError={reportError}
>
<Dashboard />
</ErrorBoundary>
</MainContent>
<Footer />
</AppErrorBoundary>
);
}
// A broken widget shows its own fallback
// Rest of the app works normallyEl límite externo captura fallos verdaderamente catastróficos. Los límites internos gestionan errores a nivel de componente, manteniendo el resto de la aplicación funcional.
Construyendo un límite de error para producción
La API integrada de límites de error de React requiere componentes de clase, pero podemos construir un envoltorio robusto que se integre con patrones modernos.
interface ErrorBoundaryProps {
children: React.ReactNode;
fallback: React.ReactNode | ((error: Error, reset: () => void) => React.ReactNode);
onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
resetKeys?: unknown[];
isolationLevel: "page" | "section" | "widget";
}
interface ErrorBoundaryState {
error: Error | null;
errorInfo: React.ErrorInfo | null;
}
class ProductionErrorBoundary extends React.Component<
ErrorBoundaryProps,
ErrorBoundaryState
> {
state: ErrorBoundaryState = { error: null, errorInfo: null };
static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
return { error };
}
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
this.setState({ errorInfo });
this.props.onError?.(error, errorInfo);
// Structured error report
reportBoundaryError({
error: {
message: error.message,
stack: error.stack,
name: error.name,
},
componentStack: errorInfo.componentStack ?? "",
isolationLevel: this.props.isolationLevel,
timestamp: new Date().toISOString(),
url: window.location.href,
});
}
componentDidUpdate(prevProps: ErrorBoundaryProps) {
if (this.state.error && this.props.resetKeys) {
const changed = this.props.resetKeys.some(
(key, i) => key !== prevProps.resetKeys?.[i]
);
if (changed) {
this.setState({ error: null, errorInfo: null });
}
}
}
reset = () => {
this.setState({ error: null, errorInfo: null });
};
render() {
if (this.state.error) {
if (typeof this.props.fallback === "function") {
return this.props.fallback(this.state.error, this.reset);
}
return this.props.fallback;
}
return this.props.children;
}
}La prop resetKeys reinicia automáticamente el límite cuando cambian valores específicos —útil para recuperarse después de una navegación o una recarga de datos. El callback reset permite reintentar manualmente desde la interfaz de respaldo.
Componentes de respaldo con significado
Un buen respaldo comunica qué falló y ofrece una salida. Los mensajes de error genéricos frustran a los usuarios que no saben si deben reintentar, refrescar o contactar con soporte.
interface FallbackProps {
error: Error;
reset: () => void;
context: string;
}
function WidgetFallback({ error, reset, context }: FallbackProps) {
return (
<div role="alert" className="widget-error">
<div className="widget-error-icon">⚠️</div>
<p className="widget-error-message">
Unable to load {context}
</p>
<div className="widget-error-actions">
<button onClick={reset} className="retry-button">
Try again
</button>
<button
onClick={() => {
navigator.clipboard.writeText(
`Error: ${error.message}\nComponent: ${context}`
);
}}
className="copy-error-button"
>
Copy error details
</button>
</div>
</div>
);
}
// Section-level fallback preserves page structure
function SectionFallback({ error, reset, context }: FallbackProps) {
return (
<div role="alert" className="section-error">
<h3>This section encountered an error</h3>
<p>The {context} section couldn't load, but you can still use the rest of the page.</p>
<button onClick={reset}>Reload section</button>
</div>
);
}Clasificación y enrutamiento de errores
No todos los errores merecen el mismo tratamiento. Los errores transitorios de red deberían reintentarse automáticamente, mientras que los errores de código requieren atención del desarrollador.
type ErrorCategory = "transient" | "data" | "render" | "fatal";
function classifyError(error: Error): ErrorCategory {
// Network and timeout errors are likely transient
if (
error.name === "TypeError" &&
error.message.includes("fetch")
) {
return "transient";
}
if (
error.message.includes("timeout") ||
error.message.includes("network")
) {
return "transient";
}
// Data shape errors suggest API contract changes
if (
error instanceof TypeError &&
(error.message.includes("Cannot read properties of undefined") ||
error.message.includes("is not a function"))
) {
return "data";
}
// Render errors from React
if (error.message.includes("render")) {
return "render";
}
return "fatal";
}
interface ErrorRecoveryStrategy {
category: ErrorCategory;
autoRetry: boolean;
maxRetries: number;
retryDelay: number;
notifyUser: boolean;
reportToMonitoring: boolean;
}
const recoveryStrategies: Record<ErrorCategory, ErrorRecoveryStrategy> = {
transient: {
category: "transient",
autoRetry: true,
maxRetries: 3,
retryDelay: 1000,
notifyUser: false,
reportToMonitoring: false,
},
data: {
category: "data",
autoRetry: false,
maxRetries: 0,
retryDelay: 0,
notifyUser: true,
reportToMonitoring: true,
},
render: {
category: "render",
autoRetry: true,
maxRetries: 1,
retryDelay: 0,
notifyUser: true,
reportToMonitoring: true,
},
fatal: {
category: "fatal",
autoRetry: false,
maxRetries: 0,
retryDelay: 0,
notifyUser: true,
reportToMonitoring: true,
},
};Estrategia de colocación de límites
Dónde colocar los límites depende de la arquitectura de componentes y los dominios de fallo. El objetivo es aislar las funcionalidades independientes unas de otras.
interface BoundaryPlacement {
level: string;
placement: string;
rationale: string;
}
const placementStrategy: BoundaryPlacement[] = [
{
level: "App shell",
placement: "Around the entire app",
rationale: "Last resort — shows full-page error with reload option",
},
{
level: "Route",
placement: "Around each routed page component",
rationale: "Page failure doesn't break navigation",
},
{
level: "Feature",
placement: "Around independent features (sidebar, chat widget, notifications)",
rationale: "Feature failure doesn't block primary workflow",
},
{
level: "Widget",
placement: "Around individual data-driven widgets (charts, lists, forms)",
rationale: "One broken data source doesn't take out the dashboard",
},
{
level: "Third-party",
placement: "Around any third-party component integration",
rationale: "External code is the most likely source of unexpected errors",
},
];
// Practical example: Dashboard with multiple independent widgets
function Dashboard() {
return (
<div className="dashboard-grid">
<ProductionErrorBoundary
isolationLevel="widget"
fallback={(error, reset) => (
<WidgetFallback error={error} reset={reset} context="Revenue Chart" />
)}
>
<RevenueChart />
</ProductionErrorBoundary>
<ProductionErrorBoundary
isolationLevel="widget"
fallback={(error, reset) => (
<WidgetFallback error={error} reset={reset} context="Active Users" />
)}
>
<ActiveUsersWidget />
</ProductionErrorBoundary>
<ProductionErrorBoundary
isolationLevel="widget"
fallback={(error, reset) => (
<WidgetFallback error={error} reset={reset} context="Recent Orders" />
)}
>
<RecentOrders />
</ProductionErrorBoundary>
</div>
);
}Reporte estructurado de errores
Los informes de límites de error deberían incluir suficiente contexto para que los desarrolladores reproduzcan y corrijan el problema sin preguntar al usuario qué ocurrió.
interface BoundaryErrorReport {
error: {
message: string;
stack: string | undefined;
name: string;
};
componentStack: string;
isolationLevel: string;
timestamp: string;
url: string;
userAgent?: string;
sessionId?: string;
}
function reportBoundaryError(report: BoundaryErrorReport): void {
// Deduplicate — don't flood monitoring with repeated errors
const errorKey =
`${report.error.name}:${report.error.message}:${report.isolationLevel}`;
if (recentErrors.has(errorKey)) {
recentErrors.get(errorKey)!.count++;
return;
}
recentErrors.set(errorKey, { report, count: 1, firstSeen: Date.now() });
// Send to monitoring service batch
errorQueue.push(report);
scheduleFlush();
}
const recentErrors = new Map<
string,
{ report: BoundaryErrorReport; count: number; firstSeen: number }
>();
const errorQueue: BoundaryErrorReport[] = [];
function scheduleFlush(): void {
if (errorQueue.length === 1) {
setTimeout(flushErrors, 5000);
}
}
function flushErrors(): void {
if (errorQueue.length === 0) return;
const batch = errorQueue.splice(0);
// Send batch to monitoring endpoint
fetch("/api/errors", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ errors: batch }),
}).catch(() => {
// Monitoring failure shouldn't cause more errors
});
}Conclusiones clave
Los límites de error son infraestructura, no algo que se añade al final. Colócalos estratégicamente a nivel de ruta, funcionalidad y widget para que los fallos queden contenidos en el radio de impacto más pequeño posible. Construye componentes de respaldo que comuniquen qué falló y ofrezcan opciones de recuperación accionables: botones de reintento, copia de detalles del error y alternativas de navegación. Clasifica los errores por categoría para aplicar estrategias de recuperación adecuadas: reintento automático de fallos transitorios, reporte de violaciones de contratos de datos y escalado de errores verdaderamente fatales. Siempre envuelve los componentes de terceros en límites, ya que el código externo es la fuente de fallos más impredecible. El signo de una aplicación bien delimitada es que los usuarios pueden identificar un widget roto de un vistazo y, sin embargo, continuar su flujo de trabajo sin interrupciones.
