@plasius/error

@plasius/error

Public package containing shared error boundary and error-handling utilities for Plasius React applications.

Install

npm install @plasius/error

Module formats

@plasius/error ships dual module outputs:

• ESM via exports.import (dist/index.js)
• CJS via exports.require (dist-cjs/index.js, explicitly marked CommonJS)

Usage

import { ErrorBoundary } from "@plasius/error";

Error boundary fallback translations

Default fallback text is resolved through @plasius/translations with bundled en-GB copy. Consumers can pass a translator to replace the default text while preserving the existing fallback override:

import { ErrorBoundary, errorBoundaryTranslationKeys } from "@plasius/error";

<ErrorBoundary
  name="CheckoutBoundary"
  translate={(key, args) => {
    if (key === errorBoundaryTranslationKeys.defaultFallback) {
      return `${args?.boundary} is unavailable.`;
    }

    return undefined;
  }}
>
  <CheckoutPage />
</ErrorBoundary>;

Error reporting with @plasius/analytics

ErrorBoundary can forward captured errors into an analytics-compatible client:

import { ErrorBoundary } from "@plasius/error";
import { createFrontendAnalyticsClient } from "@plasius/analytics";

const analytics = createFrontendAnalyticsClient({
  source: "sharedcomponents",
  endpoint: "https://analytics.example.com/collect",
});

<ErrorBoundary
  name="CheckoutBoundary"
  analyticsClient={analytics}
  errorContext={{ feature: "checkout" }}
>
  <CheckoutPage />
</ErrorBoundary>;

The boundary forwards a minimal report (boundary, error, component stack, severity, context), and @plasius/analytics handles sanitization and secure transport rules.

Whole application crash capture

installGlobalCrashReporter captures crashes outside React boundaries where available:

• browser: window.error, window.unhandledrejection
• server/runtime: process.uncaughtException, process.unhandledRejection

import {
  ErrorBoundary,
  installGlobalCrashReporter,
} from "@plasius/error";

const crashReporter = installGlobalCrashReporter({
  boundaryName: "GlobalApplication",
  analyticsClient: analytics,
  errorContext: { app: "frontend" },
});

// later during teardown
crashReporter.dispose();

Development

npm ci
npm run typecheck
npm run build
npm test

Governance

• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md
• ADRs: docs/adrs
• Legal docs: legal

License

MIT