tessl/npm-sentry--browser

Official Sentry SDK for browsers providing comprehensive error monitoring, performance tracking, user feedback collection, and session management capabilities for client-side JavaScript applications.

—

Pending

Overview

Eval results

Files

Transport

Name: tessl/npm-sentry--browser
Author: tessl

Transport layer for sending events to Sentry with offline support and custom transport options for reliable event delivery in browser environments.

Capabilities

Fetch Transport

HTTP transport using the Fetch API for sending events.

/**
 * Create a fetch-based transport for sending events
 * @param options - Transport configuration options
 * @returns Transport instance
 */
function makeFetchTransport(options: BrowserTransportOptions): Transport;

Usage Example:

import { makeFetchTransport } from "@sentry/browser";

const transport = makeFetchTransport({
  url: "https://ingest.sentry.io/api/PROJECT_ID/envelope/",
  headers: {
    "Authorization": "Bearer YOUR_AUTH_TOKEN",
    "X-Custom-Header": "value",
  },
  fetchOptions: {
    keepalive: true,
    timeout: 10000,
  },
});

Sentry.init({
  dsn: "YOUR_DSN",
  transport,
});

Offline Transport

Transport with offline capability and retry logic.

/**
 * Create an offline-capable transport wrapper
 * @param createTransport - Function to create the underlying transport
 * @returns Offline-capable transport
 */
function makeBrowserOfflineTransport(
  createTransport: (options: BrowserTransportOptions) => Transport
): (options: BrowserTransportOptions) => Transport;

Usage Example:

import { makeBrowserOfflineTransport, makeFetchTransport } from "@sentry/browser";

const offlineTransport = makeBrowserOfflineTransport(makeFetchTransport);

Sentry.init({
  dsn: "YOUR_DSN",
  transport: offlineTransport,
});

Custom Transport

Create custom transport implementations.

/**
 * Create a custom transport
 * @param options - Transport options
 * @param makeRequest - Custom request function
 * @returns Custom transport instance
 */
function createTransport(
  options: InternalBaseTransportOptions,
  makeRequest: RequestFunction
): Transport;

Multiplexed Transport

Send events to multiple destinations.

/**
 * Create a multiplexed transport that sends to multiple destinations
 * @param transports - Array of transport functions
 * @returns Multiplexed transport
 */
function makeMultiplexedTransport(
  transports: ((options: BrowserTransportOptions) => Transport)[]
): (options: BrowserTransportOptions) => Transport;

Types

Transport Options

interface BrowserTransportOptions extends BaseTransportOptions {
  /** Target URL for sending events */
  url: string;
  
  /** Custom headers to include with requests */
  headers?: { [key: string]: string };
  
  /** Fetch API options */
  fetchOptions?: RequestInit;
  
  /** Request timeout in milliseconds */
  timeout?: number;
  
  /** Enable request compression */
  compress?: boolean;
}

interface BaseTransportOptions {
  /** Buffer size for batching events */
  bufferSize?: number;
  
  /** Request timeout */
  timeout?: number;
  
  /** Transport-specific options */
  transportOptions?: Record<string, any>;
}

Transport Interface

interface Transport {
  /** Send an envelope of events */
  send(envelope: Envelope): Promise<TransportMakeRequestResponse>;
  
  /** Flush any pending events */
  flush(timeout?: number): Promise<boolean>;
}

interface TransportMakeRequestResponse {
  /** Response status code */
  statusCode?: number;
  
  /** Response headers */
  headers?: Record<string, string | null>;
}

type RequestFunction = (options: {
  body: string | Uint8Array;
  url: string;
}) => Promise<TransportMakeRequestResponse>;

Transport Configuration Examples

Basic Fetch Transport

import { makeFetchTransport } from "@sentry/browser";

Sentry.init({
  dsn: "YOUR_DSN",
  transport: makeFetchTransport({
    // Custom headers for authentication or routing
    headers: {
      "X-Custom-Auth": "token123",
      "X-Environment": "production",
    },
    
    // Fetch API options
    fetchOptions: {
      keepalive: true, // Keep connection alive
      mode: "cors",
      credentials: "omit",
    },
  }),
});

Offline-Capable Transport

import { makeBrowserOfflineTransport, makeFetchTransport } from "@sentry/browser";

const offlineTransport = makeBrowserOfflineTransport(makeFetchTransport);

Sentry.init({
  dsn: "YOUR_DSN",
  transport: offlineTransport,
  
  // Configure offline behavior
  beforeSend(event) {
    // Add offline indicator to events
    if (!navigator.onLine) {
      event.tags = {
        ...event.tags,
        sent_offline: true,
      };
    }
    return event;
  },
});

Custom Transport Implementation

import { createTransport } from "@sentry/browser";

const customTransport = createTransport(
  {
    bufferSize: 30,
    timeout: 5000,
  },
  async ({ body, url }) => {
    // Custom request logic
    const response = await fetch(url, {
      method: "POST",
      body,
      headers: {
        "Content-Type": "application/x-sentry-envelope",
        "X-Custom-Header": "custom-value",
      },
    });
    
    // Custom response handling
    return {
      statusCode: response.status,
      headers: Object.fromEntries(response.headers.entries()),
    };
  }
);

Sentry.init({
  dsn: "YOUR_DSN",
  transport: customTransport,
});

Multiplexed Transport

import { 
  makeMultiplexedTransport, 
  makeFetchTransport 
} from "@sentry/browser";

// Send events to multiple Sentry projects
const multiplexedTransport = makeMultiplexedTransport([
  // Production Sentry
  (options) => makeFetchTransport({
    ...options,
    url: "https://ingest.sentry.io/api/PROD_PROJECT/envelope/",
  }),
  
  // Development Sentry
  (options) => makeFetchTransport({
    ...options,
    url: "https://ingest.sentry.io/api/DEV_PROJECT/envelope/",
  }),
]);

Sentry.init({
  dsn: "YOUR_DSN",
  transport: multiplexedTransport,
});

Offline Behavior

The offline transport automatically:

Detects network connectivity
Queues events when offline
Retries failed requests
Respects browser storage limits
Clears old events when storage is full

Offline Configuration

// The offline transport uses browser storage
// Configure limits based on your needs
Sentry.init({
  dsn: "YOUR_DSN",
  transport: makeBrowserOfflineTransport(makeFetchTransport),
  
  // Reduce event volume for offline scenarios
  maxBreadcrumbs: 50, // Reduce breadcrumb storage
  beforeSend(event) {
    // Simplify events when offline
    if (!navigator.onLine) {
      // Remove large context data
      delete event.contexts?.response;
      delete event.extra?.largeData;
    }
    return event;
  },
});

Error Handling

Transport errors are handled gracefully:

// Transport errors don't crash the application
// Events are dropped or queued for retry

// Monitor transport failures
Sentry.addEventProcessor((event) => {
  // Add transport health data
  event.extra = {
    ...event.extra,
    transport_health: {
      online: navigator.onLine,
      last_sent: localStorage.getItem("sentry_last_sent"),
    },
  };
  return event;
});

Best Practices

Performance Optimization

// Optimize transport for performance
Sentry.init({
  dsn: "YOUR_DSN",
  transport: makeFetchTransport({
    fetchOptions: {
      keepalive: true, // Reuse connections
    },
  }),
  
  // Reduce network load
  maxBreadcrumbs: 20,
  beforeSend(event) {
    // Compress large context data
    if (event.contexts?.response?.data) {
      event.contexts.response.data = "[Compressed]";
    }
    return event;
  },
});

Network Reliability

// Use offline transport with custom retry logic
const reliableTransport = makeBrowserOfflineTransport(
  (options) => makeFetchTransport({
    ...options,
    fetchOptions: {
      timeout: 15000, // Longer timeout for reliability
      retry: 3,       // Retry failed requests
    },
  })
);

Sentry.init({
  dsn: "YOUR_DSN",
  transport: reliableTransport,
});

Install with Tessl CLI