@codeverta/error-tracking-react

Privacy-conscious browser and React client for the Codeverta error-tracing ingestion API. The package has no runtime dependency other than React, supports SSR-safe initialization, and never throws when event delivery fails.

Installation

npm install @codeverta/error-tracking-react
# or: pnpm add @codeverta/error-tracking-react
# or: yarn add @codeverta/error-tracking-react

For a portable artifact, create a tarball here:

cd packages/error-tracking-react
npm ci
npm run build
npm pack

Then install the resulting file in another application:

npm install /path/to/codeverta-error-tracking-react-0.1.0.tgz

React setup

Create a restricted browser key in the Error Tracing dashboard and add the exact frontend origins to that key. Never expose a server key in browser code.

import {
  ErrorTrackingBoundary,
  ErrorTrackingProvider,
} from "@codeverta/error-tracking-react";

export function Root() {
  return (
    <ErrorTrackingProvider
      endpoint={import.meta.env.VITE_ERROR_TRACKING_ENDPOINT}
      apiKey={import.meta.env.VITE_ERROR_TRACKING_KEY}
      environment={import.meta.env.MODE}
      release={import.meta.env.VITE_APP_RELEASE}
      application="lms-admin"
      defaultTags={{ team: "learning" }}
    >
      <ErrorTrackingBoundary
        fallback={(error, reset) => (
          <main>
            <p>Something went wrong: {error.message}</p>
            <button onClick={reset}>Try again</button>
          </main>
        )}
      >
        <App />
      </ErrorTrackingBoundary>
    </ErrorTrackingProvider>
  );
}

The provider captures global errors, unhandled promise rejections, navigation breadcrumbs, and failed fetch breadcrumbs by default.

Capturing inside components

import { useErrorTracking } from "@codeverta/error-tracking-react";

function PaymentButton() {
  const tracking = useErrorTracking();

  async function pay() {
    try {
      await createPayment();
    } catch (error) {
      tracking.captureException(error, {
        tags: { feature: "payment" },
        extra: { payment_method: "mandiri-va" },
        fingerprint: ["payment-failed", "mandiri-va"],
      });
    }
  }

  return <button onClick={pay}>Pay</button>;
}

Public API

import {
  ErrorTrackingClient,
  ErrorTrackingBoundary,
  ErrorTrackingProvider,
  addBreadcrumb,
  captureException,
  captureMessage,
  flush,
  getErrorTrackingClient,
  initErrorTracking,
  parseStackTrace,
  sanitize,
  setErrorTrackingTag,
  setErrorTrackingUser,
  useErrorTracking,
} from "@codeverta/error-tracking-react";

captureException and captureMessage return the generated event UUID when an event is accepted into the local delivery queue. They return undefined when an event is disabled, sampled, ignored, deduplicated, or the queue is full.

Setup outside React

Initialize once in the browser entry point:

import {
  addBreadcrumb,
  captureException,
  captureMessage,
  initErrorTracking,
  setErrorTrackingUser,
} from "@codeverta/error-tracking-react";

initErrorTracking({
  endpoint: import.meta.env.VITE_ERROR_TRACKING_ENDPOINT,
  apiKey: import.meta.env.VITE_ERROR_TRACKING_KEY,
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_RELEASE,
  application: "internal-erp",
});

setErrorTrackingUser({ id: user.id, email: user.email });
addBreadcrumb({ category: "ui", message: "Checkout opened" });
captureMessage("Payment retry started", { level: "warning" });
captureException(error, { tags: { module: "checkout" } });

Next.js App Router

Put the provider in a client component. Do not initialize it in a Server Component.

"use client";

import { ErrorTrackingProvider } from "@codeverta/error-tracking-react";

export function MonitoringProvider({ children }: { children: React.ReactNode }) {
  return (
    <ErrorTrackingProvider
      endpoint={process.env.NEXT_PUBLIC_ERROR_TRACKING_ENDPOINT!}
      apiKey={process.env.NEXT_PUBLIC_ERROR_TRACKING_KEY!}
      environment={process.env.NODE_ENV}
      release={process.env.NEXT_PUBLIC_APP_RELEASE}
    >
      {children}
    </ErrorTrackingProvider>
  );
}

Configuration

| Option | Default | Description | |---|---:|---| | endpoint | required | Dispatcher base URL or complete ingestion URL | | apiKey | required | Restricted browser ingestion key | | environment | required | production, staging, or another environment | | release | — | Application release/version | | application | — | Application name stored in event context | | enabled | true | Disable all capture when false | | sampleRate | 1 | Event sampling from 0 to 1 | | maxBreadcrumbs | 100 | Maximum retained breadcrumbs | | maxQueueSize | 30 | Maximum in-flight deliveries | | dedupeWindowMs | 1000 | Suppress identical messages within this window | | captureGlobalErrors | true | Capture window.onerror | | captureUnhandledRejections | true | Capture unhandled promises | | captureNavigation | true | Track History API and popstate navigation | | captureFetchBreadcrumbs | true | Record fetch status without bodies or headers | | captureConsoleErrors | false | Record console.error as breadcrumbs | | ignoreErrors | [] | String or regular-expression ignore patterns | | beforeSend | — | Modify or drop an event before delivery | | debug | false | Log delivery problems to the browser console |

Security behavior

• Password, authorization, cookie, token, secret, API-key, card, CVV, and PIN fields are recursively replaced with [Filtered].
• Request bodies and headers are never captured automatically.
• Sensitive URL query parameters and URL credentials are filtered.
• Circular structures, deep objects, long strings, arrays, stack frames, and breadcrumbs are bounded.
• Transport errors and 429 responses never affect the host application.
• beforeSend can perform application-specific redaction or return null to drop an event.

Browser-key requirements

The ingestion server must create the key with key_type: "browser" and an exact allowed_origins list:

{
  "name": "LMS Admin production",
  "key_type": "browser",
  "allowed_origins": ["https://admin.example.com"]
}

The key is expected to be visible in the compiled frontend bundle. Its security boundary is the allowed-origin restriction, ingestion-only capability, rate limit, and server-side payload sanitization. Never put a server key in VITE_* or NEXT_PUBLIC_* variables.

Compatibility

• React 18 and 19
• Modern browsers with fetch
• Node.js 18+ for builds and SSR
• ESM and CommonJS consumers
• Vite, Next.js, and other standard React bundlers

Releases

Release notes are maintained in CHANGELOG.md. This package follows semantic versioning.