0
# Offline Support
1
2
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.
3
4
**Deprecation Notice**: Use the [offline transport wrapper](http://docs.sentry.io/platforms/javascript/configuration/transports/#offline-caching) instead of this integration for new projects.
5
6
## Capabilities
7
8
### Legacy Class-based Integration (Deprecated)
9
10
```typescript { .api }
11
/**
12
* Caches offline errors and sends when connected
13
* @deprecated Use offline transport wrapper instead
14
*/
15
class Offline implements Integration {
16
/** Integration identifier */
17
static id: string;
18
19
/** Integration name */
20
readonly name: string;
21
22
/** Current hub instance */
23
hub?: Hub;
24
25
/** Maximum number of events to store while offline */
26
maxStoredEvents: number;
27
28
/** Event cache using LocalForage */
29
offlineEventStore: LocalForage;
30
31
/**
32
* Creates offline integration instance
33
* @param options - Configuration options
34
*/
35
constructor(options?: { maxStoredEvents?: number });
36
37
/**
38
* Sets up offline event processing
39
* @param addGlobalEventProcessor - Function to add event processor
40
* @param getCurrentHub - Function to get current hub
41
*/
42
setupOnce(
43
addGlobalEventProcessor: (callback: EventProcessor) => void,
44
getCurrentHub: () => Hub
45
): void;
46
}
47
```
48
49
## Configuration Options
50
51
### maxStoredEvents Option
52
53
Controls the maximum number of events cached while offline:
54
- **Default**: 30 events
55
- **Purpose**: Prevents unlimited storage growth
56
- **Behavior**: Oldest events are purged when limit exceeded
57
58
## Dependencies
59
60
This integration requires the `localforage` library for client-side storage:
61
- **Storage**: Uses IndexedDB, WebSQL, or localStorage depending on browser support
62
- **Automatic**: LocalForage instance created automatically with name `sentry/offlineEventStore`
63
64
## Behavior
65
66
### Offline Detection
67
68
The integration monitors browser connectivity:
69
- **Online check**: Uses `navigator.onLine` property
70
- **Event caching**: Stores events locally when offline
71
- **Automatic sending**: Sends cached events when online connection restored
72
73
### Event Processing
74
75
When offline (navigator.onLine === false):
76
1. Events are intercepted before sending
77
2. Cached using LocalForage with UUID keys
78
3. Events are normalized before storage
79
4. Storage is enforced to stay within maxStoredEvents limit
80
81
When online:
82
1. Cached events are retrieved and sent to Sentry
83
2. Successfully sent events are purged from cache
84
3. Process repeats for all cached events
85
86
### Connection Monitoring
87
88
The integration listens for browser online/offline events:
89
- **'online' event**: Triggers sending of all cached events
90
- **Initialization**: Sends cached events if currently online
91
92
## Usage Examples
93
94
```typescript
95
import { Offline } from '@sentry/integrations';
96
import * as Sentry from '@sentry/browser';
97
98
// Basic offline support with default settings
99
Sentry.init({
100
dsn: 'YOUR_DSN',
101
integrations: [
102
new Offline()
103
]
104
});
105
106
// Custom cache size
107
Sentry.init({
108
dsn: 'YOUR_DSN',
109
integrations: [
110
new Offline({
111
maxStoredEvents: 50 // Store up to 50 events
112
})
113
]
114
});
115
116
// Simulate offline behavior
117
// Events captured while offline are cached:
118
navigator.onLine = false; // Simulate offline
119
Sentry.captureMessage('This will be cached');
120
121
navigator.onLine = true; // Simulate back online
122
// Cached events are automatically sent
123
```
124
125
## Storage Management
126
127
### Event Caching
128
129
Events are stored with UUID keys and contain the complete normalized event data:
130
131
```typescript { .api }
132
type Item = {
133
key: string;
134
value: Event
135
};
136
```
137
138
### Storage Limits
139
140
The integration enforces storage limits:
141
- Events sorted by timestamp (newest first)
142
- Excess events beyond maxStoredEvents are purged
143
- Purging happens after each new event is cached
144
145
### Error Handling
146
147
Storage operations are wrapped with error handling:
148
- Failed cache operations are logged but don't block event processing
149
- Failed retrieval operations are logged but don't prevent other cached events from sending
150
- Storage errors don't cause integration to crash
151
152
## Migration to Transport Wrapper
153
154
**Recommended approach** for new implementations:
155
156
```typescript
157
import * as Sentry from '@sentry/browser';
158
import { makeOfflineTransport } from '@sentry/browser';
159
160
Sentry.init({
161
dsn: 'YOUR_DSN',
162
transport: makeOfflineTransport(/* transport options */)
163
});
164
```
165
166
The transport wrapper provides:
167
- Better performance and reliability
168
- Improved storage management
169
- Integration with modern Sentry architecture
170
- Active maintenance and updates
171
172
## Browser Compatibility
173
174
Requires modern browser features:
175
- **LocalForage support**: For client-side storage
176
- **Navigator.onLine**: For connectivity detection
177
- **Event listeners**: For online/offline events
178
179
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.