@scanfix/browser

Browser SDK for ScanFix error tracking. Captures uncaught errors, unhandled promise rejections, and failed HTTP requests automatically — or use the manual API.

Installation

npm install @scanfix/browser
# or
yarn add @scanfix/browser
# or
pnpm add @scanfix/browser

CDN (no bundler required)

<script src="https://cdn.scanfix.ai/sdk/v1/scanfix.min.js"></script>
<script>
  ScanFix.init({ apiKey: 'sf_your_api_key' });
</script>

Quick Start

import { init } from '@scanfix/browser';

init({
  apiKey: 'sf_your_api_key',       // Required — from your ScanFix project settings
  environment: 'production',        // Optional (default: undefined)
  apiUrl: 'https://api.scanfix.ai', // Optional — override API endpoint
});

Call init() once, as early as possible (e.g. top of main.ts or _app.tsx).

Manual Error Capture

import { captureError, log, flush } from '@scanfix/browser';

// Capture an Error object or a string
captureError(new Error('Payment failed'));
captureError('Something went wrong');

// Log at any level with optional metadata
log('WARN', 'High memory usage', { threshold: 95, current: 98 });
log('INFO', 'User signed in', { userId: 'usr_123' });

// Force-flush the queue immediately (e.g. before page navigation)
await flush();

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Required. Your ScanFix project API key (sf_...) | | environment | string | undefined | Tag logs with environment (production, staging, etc.) | | apiUrl | string | https://api.scanfix.ai | Override the ingestion endpoint | | captureUnhandledErrors | boolean | true | Auto-capture window.onerror and unhandledrejection | | captureNetworkErrors | boolean | true | Auto-capture failed fetch calls (HTTP ≥ 400) | | maxBatchSize | number | 10 | Flush when this many logs are queued | | flushIntervalMs | number | 5000 | Auto-flush interval in milliseconds |

Class API (advanced)

import { ScanFixSDK } from '@scanfix/browser';

const sdk = new ScanFixSDK({
  apiKey: 'sf_your_key',
  environment: 'staging',
  captureNetworkErrors: false, // disable fetch interceptor
});

sdk.captureError(new Error('Oops'));
sdk.log('DEBUG', 'Component mounted');
await sdk.flush();

sdk.destroy(); // clears timers and restores patched globals

Session Tracking

Every SDK instance generates a unique sessionId automatically. All logs from the same page load are grouped under that session ID, enabling the Session Timeline view in ScanFix.

console.log(sdk.currentSessionId); // e.g. "3b7e2f91-..."

React Example

// app/providers.tsx
'use client';
import { init } from '@scanfix/browser';
import { useEffect } from 'react';

export function ScanFixProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const sdk = init({ apiKey: process.env.NEXT_PUBLIC_SCANFIX_API_KEY! });
    return () => sdk.destroy();
  }, []);

  return <>{children}</>;
}

Batching & Retry

Logs are batched locally and sent in groups of up to maxBatchSize logs or every flushIntervalMs milliseconds, whichever comes first. Failed sends are retried up to 3 times with exponential backoff. On page hide/unload, the queue is flushed synchronously via navigator.sendBeacon.

Bundle Size

| Format | Minified + gzipped | |--------|--------------------| | ESM | ~4 KB | | UMD | ~5 KB | | CJS | ~11 KB |