@citadel/error-tracking

Zero-dependency error tracking SDK for JavaScript and TypeScript with React bindings.

Installation

npm install @citadel/error-tracking

Quick Start

Basic Setup

import { init } from '@citadel/error-tracking';

init({
  endpoint: 'https://citadel.example.com',
  apiKey: 'ck_...',
  environment: 'production',
  release: 'v1.2.3',
});

React Error Boundary

import { CitadelErrorBoundary } from '@citadel/error-tracking/react';

function App() {
  return (
    <CitadelErrorBoundary fallback={<ErrorPage />}>
      <YourApp />
    </CitadelErrorBoundary>
  );
}

React Hook

import { useCitadelError } from '@citadel/error-tracking/react';

function MyComponent() {
  const { captureError, captureMessage } = useCitadelError();

  const handleClick = async () => {
    try {
      await riskyOperation();
    } catch (error) {
      captureError(error);
    }
  };

  return <button onClick={handleClick}>Do Something</button>;
}

HOC Wrapper

import { withCitadelErrorBoundary } from '@citadel/error-tracking/react';

const MyComponent = () => <div>Content</div>;

export default withCitadelErrorBoundary(MyComponent, {
  fallback: <div>Error occurred</div>,
});

Features

• Zero Dependencies: Vanilla JavaScript, <5KB minified+gzipped
• Tree-Shakeable: React bindings only loaded when imported
• TypeScript Support: Full type definitions included
• Automatic Batching: Errors batched and sent every 5s
• Rate Limiting: Client-side limit of 100 errors/minute
• Defensive: Graceful degradation if Citadel unreachable
• React 18+ Compatible: Works with concurrent features

API Reference

Core SDK

init(config: CitadelConfig)

Initialize the SDK.

init({
  endpoint: 'https://citadel.example.com',
  apiKey: 'ck_...',
  environment: 'production', // optional
  release: 'v1.2.3', // optional
  captureConsoleErrors: true, // optional
  beforeSend: (error) => error, // optional
  sampleRate: 1.0, // optional (0-1)
  debug: false, // optional
});

captureError(error: Error, context?: ErrorContext)

Capture an error.

try {
  riskyOperation();
} catch (error) {
  captureError(error, {
    extra: { userId: '123' },
  });
}

captureMessage(message: string, context?: ErrorContext)

Capture a message.

captureMessage('Something unexpected happened', {
  extra: { details: 'Additional context' },
});

setContext(context: ErrorContext)

Set global context for all errors.

setContext({
  user: { id: '123', email: '[email protected]' },
  extra: { appVersion: '1.0.0' },
});

React Bindings

<CitadelErrorBoundary>

Error boundary component.

<CitadelErrorBoundary
  fallback={<ErrorPage />} // or function
  onError={(error, componentStack) => {}}
  context={{ extra: { page: 'dashboard' } }}
>
  <App />
</CitadelErrorBoundary>

withCitadelErrorBoundary(Component, options?)

HOC to wrap component with error boundary.

const WrappedComponent = withCitadelErrorBoundary(MyComponent, {
  fallback: <div>Error</div>,
  onError: (error, stack) => console.log(error),
  context: { extra: { component: 'MyComponent' } },
});

useCitadelError()

Hook for manual error reporting.

const { captureError, captureMessage, setContext, isInitialized } =
  useCitadelError();

Defensive Features

• Infinite Loop Protection: Error boundary never throws
• Stack Truncation: Stack traces limited to 50KB
• Component Stack Truncation: Limited to 50 frames
• Rate Limiting: Max 100 errors/minute client-side
• Graceful Degradation: App continues if Citadel unreachable

Bundle Size

• Core SDK: ~3KB minified+gzipped
• React bindings: ~2KB minified+gzipped (when imported)
• Total (with React): ~5KB minified+gzipped

License

MIT