Offline Support

Legacy class-based integration for caching events when offline and sending them when connection is restored. This integration is deprecated in favor of the offline transport wrapper.

Deprecation Notice: Use the offline transport wrapper instead of this integration for new projects.

Capabilities

Legacy Class-based Integration (Deprecated)

/**
 * Caches offline errors and sends when connected
 * @deprecated Use offline transport wrapper instead
 */
class Offline implements Integration {
  /** Integration identifier */
  static id: string;
  
  /** Integration name */
  readonly name: string;
  
  /** Current hub instance */
  hub?: Hub;
  
  /** Maximum number of events to store while offline */
  maxStoredEvents: number;
  
  /** Event cache using LocalForage */
  offlineEventStore: LocalForage;
  
  /**
   * Creates offline integration instance
   * @param options - Configuration options
   */
  constructor(options?: { maxStoredEvents?: number });
  
  /**
   * Sets up offline event processing
   * @param addGlobalEventProcessor - Function to add event processor
   * @param getCurrentHub - Function to get current hub
   */
  setupOnce(
    addGlobalEventProcessor: (callback: EventProcessor) => void, 
    getCurrentHub: () => Hub
  ): void;
}

Configuration Options

maxStoredEvents Option

Controls the maximum number of events cached while offline:

• Default: 30 events
• Purpose: Prevents unlimited storage growth
• Behavior: Oldest events are purged when limit exceeded

Dependencies

This integration requires the localforage library for client-side storage:

• Storage: Uses IndexedDB, WebSQL, or localStorage depending on browser support
• Automatic: LocalForage instance created automatically with name sentry/offlineEventStore

Behavior

Offline Detection

The integration monitors browser connectivity:

• Online check: Uses navigator.onLine property
• Event caching: Stores events locally when offline
• Automatic sending: Sends cached events when online connection restored

Event Processing

When offline (navigator.onLine === false):

1. Events are intercepted before sending
2. Cached using LocalForage with UUID keys
3. Events are normalized before storage
4. Storage is enforced to stay within maxStoredEvents limit

When online:

1. Cached events are retrieved and sent to Sentry
2. Successfully sent events are purged from cache
3. Process repeats for all cached events

Connection Monitoring

The integration listens for browser online/offline events:

• 'online' event: Triggers sending of all cached events
• Initialization: Sends cached events if currently online

Usage Examples

import { Offline } from '@sentry/integrations';
import * as Sentry from '@sentry/browser';

// Basic offline support with default settings
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    new Offline()
  ]
});

// Custom cache size
Sentry.init({
  dsn: 'YOUR_DSN', 
  integrations: [
    new Offline({
      maxStoredEvents: 50  // Store up to 50 events
    })
  ]
});

// Simulate offline behavior
// Events captured while offline are cached:
navigator.onLine = false;  // Simulate offline
Sentry.captureMessage('This will be cached');

navigator.onLine = true;   // Simulate back online
// Cached events are automatically sent

Storage Management

Event Caching

Events are stored with UUID keys and contain the complete normalized event data:

type Item = { 
  key: string; 
  value: Event 
};

Storage Limits

The integration enforces storage limits:

• Events sorted by timestamp (newest first)
• Excess events beyond maxStoredEvents are purged
• Purging happens after each new event is cached

Error Handling

Storage operations are wrapped with error handling:

• Failed cache operations are logged but don't block event processing
• Failed retrieval operations are logged but don't prevent other cached events from sending
• Storage errors don't cause integration to crash

Migration to Transport Wrapper

Recommended approach for new implementations:

import * as Sentry from '@sentry/browser';
import { makeOfflineTransport } from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN',
  transport: makeOfflineTransport(/* transport options */)
});

The transport wrapper provides:

• Better performance and reliability
• Improved storage management
• Integration with modern Sentry architecture
• Active maintenance and updates

Browser Compatibility

Requires modern browser features:

• LocalForage support: For client-side storage
• Navigator.onLine: For connectivity detection
• Event listeners: For online/offline events

This integration is primarily useful for Single Page Applications where users may experience intermittent connectivity issues and you want to ensure error events are not lost during offline periods.