0
# Frame Rewriting
1

2
Transforms stack frame filenames using configurable rules. This integration is useful for normalizing file paths in different deployment environments, removing sensitive paths, or creating consistent frame references.
3

4
## Capabilities
5

6
### Modern Function-based Integration
7

8
```typescript { .api }
9
/**
10
 * Rewrites event frame paths using configurable transformation rules
11
 * @param options - Frame rewriting configuration
12
 * @returns Integration instance that processes stack frames
13
 */
14
function rewriteFramesIntegration(options?: RewriteFramesOptions): Integration;
15

16
interface RewriteFramesOptions {
17
  /** Root path to strip from filenames */
18
  root?: string;
19
  /** Prefix to add to rewritten filenames. Default: 'app:///' */
20
  prefix?: string;
21
  /** Custom frame processing function */
22
  iteratee?: StackFrameIteratee;
23
}
24

25
type StackFrameIteratee = (frame: StackFrame) => StackFrame;
26
```
27

28
### Legacy Class-based Integration (Deprecated)
29

30
```typescript { .api }
31
/**
32
 * Legacy class-based frame rewriting integration
33
 * @deprecated Use rewriteFramesIntegration() instead
34
 */
35
class RewriteFrames implements Integration {
36
  constructor(options?: { 
37
    root?: string; 
38
    prefix?: string; 
39
    iteratee?: StackFrameIteratee 
40
  });
41
  name: string;
42
  processEvent(event: Event): Event;
43
}
44
```
45

46
## Configuration Options
47

48
### root Option
49

50
Base path to strip from filenames before applying prefix:
51
- **Purpose**: Remove deployment-specific or sensitive path prefixes
52
- **Example**: `/var/www/app` → strips this from `/var/www/app/src/utils.js`
53
- **Cross-platform**: Handles both Unix and Windows paths
54

55
### prefix Option
56

57
String to prepend to processed filenames:
58
- **Default**: `'app:///'`
59
- **Purpose**: Create consistent, recognizable frame references
60
- **Example**: `utils.js` → `app:///utils.js`
61

62
### iteratee Option
63

64
Custom frame transformation function:
65
- **Signature**: `(frame: StackFrame) => StackFrame`
66
- **Purpose**: Complete control over frame processing
67
- **Overrides**: When provided, replaces default transformation logic
68

69
## Default Behavior
70

71
Without custom iteratee, the integration applies these transformations:
72

73
### Path Detection
74

75
Automatically detects Windows vs Unix paths:
76
- **Windows**: Paths starting with drive letters (`C:\`) or containing backslashes
77
- **Unix**: Paths starting with forward slash (`/`)
78

79
### Windows Path Processing
80

81
For Windows-style paths:
82
1. Remove drive letter prefix (e.g., `C:`)
83
2. Convert backslashes to forward slashes
84
3. Apply root stripping and prefix
85

86
### Unix Path Processing
87

88
For Unix-style paths:
89
1. Apply root stripping (if configured)
90
2. Use basename if no root specified
91
3. Apply prefix
92

93
## Usage Examples
94

95
```typescript
96
import { rewriteFramesIntegration } from '@sentry/integrations';
97
import * as Sentry from '@sentry/browser';
98

99
// Basic prefix-only transformation
100
Sentry.init({
101
  dsn: 'YOUR_DSN',
102
  integrations: [
103
    rewriteFramesIntegration({
104
      prefix: 'myapp:///'
105
    })
106
  ]
107
});
108

109
// Strip deployment path and add prefix
110
Sentry.init({
111
  dsn: 'YOUR_DSN',
112
  integrations: [
113
    rewriteFramesIntegration({
114
      root: '/var/www/myapp',
115
      prefix: 'app:///'
116
    })
117
  ]
118
});
119

120
// Custom transformation logic
121
Sentry.init({
122
  dsn: 'YOUR_DSN',
123
  integrations: [
124
    rewriteFramesIntegration({
125
      iteratee: (frame) => {
126
        if (frame.filename) {
127
          // Custom logic: mask user-specific paths
128
          frame.filename = frame.filename.replace(
129
            /\/Users\/[^\/]+/,
130
            '/Users/***'
131
          );
132
          // Add custom prefix
133
          frame.filename = `custom:///${frame.filename}`;
134
        }
135
        return frame;
136
      }
137
    })
138
  ]
139
});
140
```
141

142
## Path Transformation Examples
143

144
### Default Behavior
145

146
```javascript
147
// Input frames:
148
'/var/www/app/src/utils.js'       → 'app:///src/utils.js'
149
'C:\\app\\src\\utils.js'          → 'app:///src/utils.js'  
150
'/home/user/project/main.js'      → 'app:///main.js'
151
```
152

153
### With Root Stripping
154

155
```javascript
156
// Configuration: { root: '/var/www/app', prefix: 'myapp:///' }
157
'/var/www/app/src/utils.js'       → 'myapp:///src/utils.js'
158
'/var/www/app/lib/helper.js'      → 'myapp:///lib/helper.js'
159
'/different/path/file.js'         → 'myapp:///file.js'
160
```
161

162
### Cross-platform Consistency
163

164
```javascript
165
// Both produce same result:
166
'C:\\Users\\dev\\project\\src\\main.js'  → 'app:///src/main.js'
167
'/home/dev/project/src/main.js'          → 'app:///src/main.js'
168
```
169

170
## Stack Frame Processing
171

172
The integration processes all stack frames in:
173
- **Exception events**: All exception values and their stacktraces
174
- **Frame-by-frame**: Each frame individually processed
175
- **Preserves metadata**: Only filename is modified, other frame data unchanged
176

177
## Common Use Cases
178

179
1. **Deployment Path Hiding**: Remove server-specific paths from production stacktraces
180
2. **Cross-platform Consistency**: Normalize Windows/Unix path differences
181
3. **Sensitive Path Masking**: Hide user directories or internal system paths
182
4. **Logical Grouping**: Add prefixes to identify different application components
183
5. **Development vs Production**: Different prefixes for different environments
184

185
This integration is essential for production applications where stack frame paths need to be normalized or sanitized for security and consistency.