@nexussdk/tracker

Ultra-resilient, production-grade client crash ingestion and telemetry SDK with automated PII sanitization, Core Web Vitals, and pluggable transports (< 5KB gzipped).

Key Features

• Automated PII Scrubbing: Recursive sanitization of emails, JWT tokens, credit card numbers, passwords, and authorization headers before transmission.
• Deterministic Fingerprinting: Parses stack traces across V8, SpiderMonkey, and JSCore to generate consistent, deterministic error group hashes without async crypto overhead.
• Client-Side Deduplication & Sampling: Sliding window deduplication prevents telemetry storms during rapid loops. Configurable sampling rate and session crash limits.
• Pluggable Transports: Supports fetch (with keepalive and navigator.sendBeacon fallback during page unloads), console logging, localStorage offline buffers, or custom callback functions.
• Zero-Dependency Web Vitals: Observes LCP, CLS, FID, TTFB, INP, FCP, and long tasks (>50ms) using the browser's native PerformanceObserver API.
• Framework-Agnostic Error Boundary Core: NexusGuardCore provides crash isolation and recovery logic for any JavaScript runtime.
• Built-in Local Ingestion Server: nexus-dev CLI offers an instant local HTTP ingestion server with real-time SSE Web GUI for offline development.

Installation

pnpm add @nexussdk/tracker
# or
npm install @nexussdk/tracker

(If using React or Vue, install @nexussdk/sdk instead for built-in hooks and components).

Quickstart (Vanilla JS / TypeScript)

import { NexusTrackerClient, attachWebVitals, NexusGuardCore } from '@nexussdk/tracker';

// 1. Initialize client
const tracker = new NexusTrackerClient({
  apiKey: 'pk_live_your_api_key',
  environment: 'production',
  sampling: {
    rate: 1.0,           // 100% sampling
    dedupeWindow: 10000, // 10s deduplication window
    maxPerSession: 50,   // Crash-loop defense: cap at 50 errors per session
  },
  transport: 'fetch',
});

// 2. Attach Web Vitals observer
const detachVitals = attachWebVitals(tracker, {
  poorRatingOnly: true,
  captureAsEvents: false, // captured as breadcrumbs
});

// 3. Capture errors manually
try {
  executePayment();
} catch (err) {
  tracker.captureError(err, { orderId: 'ord_123' });
}

// 4. Capture informational/warning messages
tracker.captureMessage('High memory usage detected', 'warning', { heapMb: 420 });

// 5. Add custom breadcrumbs
tracker.addBreadcrumb({
  category: 'ui.click',
  message: 'User clicked checkout button',
  level: 'info',
});

Configuration Options (NexusTrackerOptions)

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | apiKey | string | Env | Public API key (pk_live_...) | | baseUrl | string | Env | Ingestion endpoint URL (e.g. https://telemetry.example.com) | | environment | string | 'production' | Target environment name | | autoCapture | boolean | true | Binds global window.onerror and unhandledrejection handlers | | tags | Record<string, string> | {} | Global static tags attached to every captured event | | extra | Record<string, unknown> | {} | Additional structured context attached to all events | | sampling | SamplingConfig | Default | Rate limiting and deduplication parameters | | transport | TransportPlugin | 'fetch' | Delivery dispatcher: 'fetch', 'console', 'localStorage', or custom fn | | maxBreadcrumbs | number | 50 | In-memory ring buffer capacity for breadcrumbs | | beforeSend | Function | undefined | Hook to inspect, modify, or discard events prior to transmission |

Sampling Configuration (SamplingConfig)

export interface SamplingConfig {
  /** Sampling rate: 0.0 (0%) to 1.0 (100%). Default: 1.0 */
  rate?: number;
  /** Deduplication sliding window in milliseconds. Default: 10000 */
  dedupeWindow?: number;
  /** Max unique error fingerprints captured per browser session. Default: 100 */
  maxPerSession?: number;
}

Universal Error Boundary (NexusGuardCore)

const guard = new NexusGuardCore({
  tracker,
  onError: (error, info) => {
    console.warn(`Protected crash [Ref: ${info.errorId}]:`, error);
  },
});

// Subscribe to state changes
const unsubscribe = guard.subscribe((info) => {
  if (info) {
    document.getElementById('root')!.innerHTML = `
      <div class="alert">
        <h2>App Crash Protected</h2>
        <p>Reference: ${info.errorId}</p>
        <button id="retry">Retry</button>
      </div>
    `;
    document.getElementById('retry')?.addEventListener('click', () => guard.recover());
  }
});

Local Dev Server (nexus-dev)

The tracker package includes an offline telemetry receiver and dashboard CLI:

# Start local ingestion server on port 4567
npx nexus-dev --port 4567
# or in monorepo
pnpm nexus-dev

• Web Dashboard: http://localhost:4567/
• Ingestion Endpoint: http://localhost:4567/api/v1/telemetry/errors
• SSE Stream: http://localhost:4567/sse

Framework Compatibility Matrix

@nexussdk/tracker has zero runtime dependencies and runs on any modern browser or Node.js backend:

| Framework / Runtime | Supported Versions | Mechanism | Documentation | | :--- | :--- | :--- | :--- | | React / Next.js | React 16.8 – 19 / Next.js 13 – 16 | <NexusGuard>, useNexus, Error Boundary | React Error Boundary Guide | | Vue / Nuxt | Vue 2.7 & 3.x / Nuxt 3 & 4 | app.config.errorHandler, error.vue | Vue Error Tracking Guide | | Angular | Angular 14 – 19+ / AngularJS | ErrorHandler provider, HTTP interceptors | Angular Error Tracking Guide | | Svelte / SvelteKit | Svelte 3 – 5 / SvelteKit 1 & 2 | handleError hooks, +error.svelte | Svelte Error Tracking Guide | | Node.js Backend | Node.js 18, 20, 22 LTS | Express / Fastify error middleware | Node.js Backend Guide |

License

MIT © Nexus Platform