crashguard-react

Production-ready React error boundaries, crash reporting helpers, and fallback UI for enterprise admin panels, CRM, ERP, dashboards, internal portals, and modern React apps.

Built by Pradeep Kumar Sheoran (Developer) at BSG Technologies.

Official Website: https://bsgtechnologies.com
Visit here to meet, learn, contribute, and discuss new topics with us.

Contact / WhatsApp: +91-8595147850
Donation / UPI Support: +91-8595147850

Why CrashGuard?

React error boundaries catch render-time crashes, but production teams usually need more than a fallback screen. crashguard-react adds the operational pieces around the boundary:

• Structured crash reports with stable error IDs and fingerprints
• Provider-level defaults for app name, metadata, reporter, severity, and display policy
• Privacy controls for redaction, custom sanitization, and report blocking
• Duplicate suppression and session limits to protect your reporting endpoint
• Async and event-handler handoff through hooks
• Ready-to-use API error, network error, fallback, and internal report views
• Fully customizable labels, callbacks, fallback UI, metadata, report delivery, and policy behavior

Use it when a dashboard or internal app should fail gracefully, show a support reference ID, and send safe diagnostic data to your own endpoint.

Features

• React 18+ compatible error boundary for modern React applications
• Works with React 19 projects through peer dependency compatibility
• Retry and reset support with resetKeys and onReset
• Custom fallback renderer or custom fallback React node
• Async/event error handoff with useErrorHandler
• Manual crash reporting with useCrashReporter
• Crash callback aliases: onError, onGuardianSignal, reporter, and sentinelReporter
• Report lifecycle hooks: beforeReport, onReportSuccess, onReportFailure
• Privacy controls: redactFields, sanitizeReport, and report blocking
• Deduplication with dedupeWindowMs
• Session delivery cap with maxReportsPerSession
• Severity support: low, medium, high, critical
• Error ID and fingerprint generation for support workflows
• Metadata, app name, module name, URL, user agent, timestamp, and component stack support
• Production-safe defaults that hide stack traces unless showDetails is enabled
• API error normalization and ApiErrorView
• Network error detection and NetworkErrorView
• Internal CrashReportView for admin/debug screens
• Fully typed TypeScript API
• ESM + CJS output and generated declaration files
• Storybook-ready component documentation
• Local Vite React demo app
• Original SDK implementation with no bundled third-party crash-reporting SDK

Original Code And Dependency Policy

crashguard-react is an original CrashGuard SDK implementation created by Pradeep Kumar Sheoran for BSG Technologies.

• No copied source code from another crash-reporting library.
• No third-party runtime monitoring SDK.
• No third-party UI framework or CSS framework bundled into the SDK runtime.
• No runtime dependency bundle except React and React DOM peer dependencies required for React components and hooks.
• Build, test, lint, demo, and documentation tools are development-only and are not shipped as runtime SDK code.

React and React DOM remain peer dependencies because this package exports React components and hooks. The published package ships CrashGuard build output, type declarations, README, license, notice, changelog, security documentation, and docs.

Installation

npm install crashguard-react

yarn add crashguard-react

pnpm add crashguard-react

Quickstart

import { AppErrorBoundary } from "crashguard-react";

async function sendToServer(report) {
  await fetch("/api/crash-report", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(report)
  });
}

export function App() {
  return (
    <AppErrorBoundary
      appName="BSG Enterprise Admin"
      moduleName="DashboardShell"
      onGuardianSignal={sendToServer}
    >
      <Dashboard />
    </AppErrorBoundary>
  );
}

Implementation Guide

For a complete setup guide, see docs/IMPLEMENTATION_GUIDE.md.

Recommended production setup:

import { AppErrorBoundary, CrashGuardProvider } from "crashguard-react";

const sendCrashReport = async (report) => {
  await fetch("/api/crash-report", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(report)
  });
};

export function Root() {
  return (
    <CrashGuardProvider
      appName="BSG Enterprise CRM"
      sentinelReporter={sendCrashReport}
      showDetails={import.meta.env.DEV}
      severity="high"
      metadata={{ release: "2026.07", environment: "production" }}
      redactFields={["metadata.token", "metadata.email", "userAgent"]}
      dedupeWindowMs={30000}
      maxReportsPerSession={20}
    >
      <AppErrorBoundary moduleName="DashboardShell">
        <App />
      </AppErrorBoundary>
    </CrashGuardProvider>
  );
}

Customization Options

For all customization examples, see docs/CUSTOMIZATION.md.

| Area | Options | | --- | --- | | Branding | appName, moduleName, metadata | | Fallback UI | fallback, retryLabel, homeLabel, onGoHome, showDetails | | Reporting | onError, onGuardianSignal, reporter, sentinelReporter | | Privacy | redactFields, sanitizeReport, beforeReport | | Reliability | dedupeWindowMs, maxReportsPerSession, onReportFailure | | Recovery | resetKeys, onReset, resetError | | API UI | ApiErrorView, normalizeApiError, retry callbacks | | Network UI | NetworkErrorView, retry callbacks, support message |

Custom fallback example:

<AppErrorBoundary
  fallback={({ errorId, resetError }) => (
    <section role="alert">
      <h2>Section unavailable</h2>
      <p>Reference ID: {errorId}</p>
      <button type="button" onClick={resetError}>
        Reload section
      </button>
    </section>
  )}
>
  <UserTable />
</AppErrorBoundary>

Response / Report Shape

CrashGuard sends a complete report object to onError, onGuardianSignal, provider reporter, or provider sentinelReporter.

type ErrorReport = {
  errorId: string;
  fingerprint?: string;
  severity?: "low" | "medium" | "high" | "critical";
  message: string;
  name: string;
  stack?: string;
  componentStack?: string;
  appName?: string;
  moduleName?: string;
  metadata?: Record<string, unknown>;
  url?: string;
  userAgent?: string;
  timestamp: string;
};

Example API response from your backend:

{
  "ok": true,
  "ticketId": "CG-2026-0001",
  "message": "Crash report received"
}

API Error UI

import { ApiErrorView, normalizeApiError } from "crashguard-react";

const apiError = normalizeApiError(error);

<ApiErrorView
  status={apiError.status}
  title={apiError.title}
  message={apiError.message}
  onRetry={apiError.isRetryable ? refetch : undefined}
/>;

Network Error UI

import { NetworkErrorView } from "crashguard-react";

<NetworkErrorView
  onRetry={refetch}
  contactSupportMessage="If this continues, contact your support team."
/>;

Async And Event Errors

React error boundaries do not automatically catch errors from event handlers or async tasks. Use useErrorHandler when you want to hand the error to the nearest boundary.

import { useErrorHandler } from "crashguard-react";

function SaveButton() {
  const throwError = useErrorHandler();

  const save = async () => {
    try {
      await saveUser();
    } catch (error) {
      throwError(error);
    }
  };

  return <button onClick={save}>Save</button>;
}

Use useCrashReporter when you want to report an error without replacing the current UI.

import { useCrashReporter } from "crashguard-react";

function UserActions() {
  const { reportError } = useCrashReporter({
    appName: "BSG Enterprise CRM",
    moduleName: "User Management"
  });

  async function createUser() {
    try {
      await api.createUser();
    } catch (error) {
      await reportError(error, {
        metadata: { action: "create-user", userId: 10 }
      });
    }
  }
}

Live Demo

A local Vite demo lives in examples/vite-react-app. It includes render-crash controls, async crash reporting, API and network fallback examples, sanitization policy settings, and a live report feed.

cd examples/vite-react-app
npm install
npm run dev

Then open the URL printed by Vite, usually:

http://localhost:5173

Full demo instructions are available in docs/LIVE_DEMO.md.

Storybook

Run the component playground:

npm run dev

Build Storybook:

npm run build-storybook

Build, Test, And Publish Check

npm run verify
npm run pack:dry-run

Or run each check separately:

npm run typecheck
npm run test
npm run lint
npm run build

npm run verify runs type checking, tests, linting, and the production build. npm run pack:dry-run verifies the exact files that would be published to npm.

Public API

export {
  CrashGuardProvider,
  AppErrorBoundary,
  ErrorFallback,
  ApiErrorView,
  NetworkErrorView,
  CrashReportView,
  useErrorHandler,
  useCrashReporter,
  createErrorId,
  createErrorFingerprint,
  normalizeError,
  getErrorInfo,
  isNetworkError,
  isApiError,
  normalizeApiError,
  fromFetchError,
  sanitizeErrorReport,
  deliverErrorReport,
  resetCrashReportSession
};

Keywords And Hashtags

react, react-error-boundary, error-boundary, crash-reporting, error-reporting, fallback-ui, typescript, enterprise, admin-panel, crm, erp, dashboard, network-error, api-error, react-18, react-19, vite, storybook

#React #ReactJS #TypeScript #ErrorBoundary #CrashReporting #ErrorReporting #EnterpriseApps #AdminPanel #CRM #ERP #Dashboard #Frontend #Vite #Storybook #BSGTechnologies

Support, Contact, And Donation

Developer: Pradeep Kumar Sheoran (Developer)
Company: BSG Technologies
Contact / WhatsApp: +91-8595147850
Official Website: https://bsgtechnologies.com
Donation / UPI Support: +91-8595147850

Visit https://bsgtechnologies.com to meet, learn, contribute, and discuss new topics with us.

License

MIT