0
# Context Lines
1
2
Browser-only integration that adds source context lines to stack frames pointing to inline JavaScript code in HTML pages. This integration helps debug errors in inline scripts that cannot be accessed by Sentry's backend for context collection.
3
4
## Capabilities
5
6
### Modern Function-based Integration
7
8
```typescript { .api }
9
/**
10
* Collects source context lines for inline JavaScript in HTML pages
11
* @param options - Configuration for context line collection
12
* @returns Integration instance that adds context to frames
13
*/
14
function contextLinesIntegration(options?: ContextLinesOptions): Integration;
15
16
interface ContextLinesOptions {
17
/** Number of context lines for each frame. Defaults to 7. Set to 0 to disable. */
18
frameContextLines?: number;
19
}
20
```
21
22
### Legacy Class-based Integration (Deprecated)
23
24
```typescript { .api }
25
/**
26
* Legacy class-based context lines integration
27
* @deprecated Use contextLinesIntegration() instead
28
*/
29
class ContextLines implements Integration {
30
constructor(options?: { frameContextLines?: number });
31
name: string;
32
processEvent(event: Event): Event;
33
}
34
```
35
36
## Configuration Options
37
38
### frameContextLines Option
39
40
Controls the number of source lines to include around each frame:
41
- **Default**: 7 lines (3 before + target line + 3 after)
42
- **Disable**: 0 (no context collection)
43
- **Custom**: Any positive number for more/less context
44
45
## Behavior
46
47
### Target Frames
48
49
Only processes stack frames that point to:
50
- **Current HTML page**: Frame filename matches current page URL
51
- **Inline JavaScript**: Code embedded directly in HTML (not external JS files)
52
- **Valid line numbers**: Frames with line number information
53
54
### Context Collection
55
56
The integration:
57
1. Extracts complete HTML source from `document.documentElement.innerHTML`
58
2. Converts to line array with DOCTYPE and html tags
59
3. Maps stack frame line numbers to HTML lines
60
4. Adds surrounding context lines to matching frames
61
62
### Browser Environment Only
63
64
This integration:
65
- **Requires DOM**: Must have access to `document` and `window`
66
- **Current page only**: Only works for the currently loaded HTML page
67
- **No external files**: Cannot process external JavaScript files
68
69
## Usage Examples
70
71
```typescript
72
import { contextLinesIntegration } from '@sentry/integrations';
73
import * as Sentry from '@sentry/browser';
74
75
// Default 7 lines of context
76
Sentry.init({
77
dsn: 'YOUR_DSN',
78
integrations: [
79
contextLinesIntegration()
80
]
81
});
82
83
// More context lines for better debugging
84
Sentry.init({
85
dsn: 'YOUR_DSN',
86
integrations: [
87
contextLinesIntegration({
88
frameContextLines: 15
89
})
90
]
91
});
92
93
// Minimal context for performance
94
Sentry.init({
95
dsn: 'YOUR_DSN',
96
integrations: [
97
contextLinesIntegration({
98
frameContextLines: 3
99
})
100
]
101
});
102
103
// Disable context collection
104
Sentry.init({
105
dsn: 'YOUR_DSN',
106
integrations: [
107
contextLinesIntegration({
108
frameContextLines: 0
109
})
110
]
111
});
112
```
113
114
## HTML Source Processing
115
116
The integration reconstructs the HTML document structure:
117
118
```html
119
<!DOCTYPE html>
120
<html>
121
<head>
122
<title>My App</title>
123
</head>
124
<body>
125
<script>
126
function buggyFunction() {
127
throw new Error('Inline script error'); // Line gets context
128
}
129
buggyFunction();
130
</script>
131
</body>
132
</html>
133
```
134
135
When an error occurs in the inline script, the integration adds context lines showing the surrounding HTML and JavaScript code.
136
137
## Exported Test Utilities
138
139
```typescript { .api }
140
/**
141
* Applies source context to a single frame (exported for testing)
142
* @param frame - Stack frame to process
143
* @param htmlLines - Array of HTML source lines
144
* @param htmlFilename - Current page filename
145
* @param linesOfContext - Number of context lines to include
146
* @returns Frame with added context
147
*/
148
function applySourceContextToFrame(
149
frame: StackFrame,
150
htmlLines: string[],
151
htmlFilename: string,
152
linesOfContext: number
153
): StackFrame;
154
```
155
156
## Use Cases
157
158
This integration is particularly valuable for:
159
160
1. **Single Page Applications**: SPAs with significant inline JavaScript
161
2. **Dynamic HTML**: Applications generating HTML with embedded scripts
162
3. **Login-protected pages**: Pages Sentry backend cannot access for context
163
4. **Development debugging**: Enhanced local debugging of inline scripts
164
5. **Legacy applications**: Apps with mixed inline/external JavaScript
165
166
## Limitations
167
168
- **External JS files**: Cannot process external JavaScript files (handled by backend)
169
- **Cross-origin restrictions**: Limited by browser same-origin policies
170
- **Performance impact**: Processes entire HTML source for each error
171
- **Browser only**: Not available in Node.js or server-side environments
172
173
This integration complements Sentry's backend context collection by handling the specific case of inline JavaScript that cannot be accessed remotely.