0
# Rollup Plugin Sourcemaps
1
2
Rollup Plugin Sourcemaps is a plugin for loading files with existing source maps during the Rollup bundling process. It automatically detects and resolves sourceMappingURL comments in source code, loads external source map files, and integrates them into Rollup's compilation pipeline to maintain accurate debugging information.
3
4
## Package Information
5
6
- **Package Name**: rollup-plugin-sourcemaps
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install rollup-plugin-sourcemaps`
10
11
## Core Imports
12
13
```typescript
14
import sourcemaps from "rollup-plugin-sourcemaps";
15
import type { SourcemapsPluginOptions } from "rollup-plugin-sourcemaps";
16
import type { Plugin } from "rollup";
17
import type { CreateFilter } from "@rollup/pluginutils";
18
```
19
20
For CommonJS:
21
22
```javascript
23
const sourcemaps = require("rollup-plugin-sourcemaps");
24
```
25
26
## Basic Usage
27
28
```typescript
29
import sourcemaps from "rollup-plugin-sourcemaps";
30
31
export default {
32
input: 'src/index.js',
33
plugins: [sourcemaps()],
34
output: {
35
sourcemap: true,
36
file: 'dist/bundle.js',
37
},
38
};
39
```
40
41
With options:
42
43
```typescript
44
import sourcemaps from "rollup-plugin-sourcemaps";
45
46
export default {
47
input: 'src/index.js',
48
plugins: [
49
sourcemaps({
50
include: '**/*.js',
51
exclude: 'node_modules/**',
52
})
53
],
54
output: {
55
sourcemap: true,
56
file: 'dist/bundle.js',
57
},
58
};
59
```
60
61
## Capabilities
62
63
### Plugin Factory Function
64
65
Creates a Rollup plugin instance for handling source maps in the build process.
66
67
```typescript { .api }
68
/**
69
* Creates a Rollup plugin for loading files with existing source maps
70
* @param options - Optional configuration for the plugin
71
* @returns Rollup plugin instance
72
*/
73
export default function sourcemaps(options?: SourcemapsPluginOptions): Plugin;
74
```
75
76
The returned plugin implements the Rollup Plugin interface:
77
78
```typescript { .api }
79
interface Plugin {
80
/** Plugin identifier */
81
name: string;
82
/**
83
* Processes files and their source maps during the load phase
84
* @param id - File identifier/path being loaded
85
* @returns Promise resolving to null (delegate to next plugin), code string, or code with source map
86
*/
87
load(id: string): Promise<null | string | { code: string; map: ExistingRawSourceMap }>;
88
}
89
```
90
91
**Usage Examples:**
92
93
```typescript
94
// Basic usage with no options
95
const plugin = sourcemaps();
96
97
// With file filtering
98
const plugin = sourcemaps({
99
include: ['src/**/*.js', 'lib/**/*.ts'],
100
exclude: ['**/*.test.js']
101
});
102
103
// With custom file reader
104
const plugin = sourcemaps({
105
readFile: (path, callback) => {
106
// Custom file reading logic
107
fs.readFile(path, callback);
108
}
109
});
110
```
111
112
## Plugin Options
113
114
```typescript { .api }
115
export interface SourcemapsPluginOptions {
116
/**
117
* Pattern or array of patterns to include files for source map processing
118
* Uses the same format as @rollup/pluginutils createFilter
119
*/
120
include?: Parameters<CreateFilter>[0];
121
122
/**
123
* Pattern or array of patterns to exclude files from source map processing
124
* Uses the same format as @rollup/pluginutils createFilter
125
*/
126
exclude?: Parameters<CreateFilter>[1];
127
128
/**
129
* Custom file reading function for loading source files and source maps
130
* Defaults to fs.readFile if not provided
131
*/
132
readFile?(
133
path: string,
134
callback: (error: Error | null, data: Buffer | string) => void
135
): void;
136
}
137
138
/** Type alias for the CreateFilter function from @rollup/pluginutils */
139
type CreateFilter = (include?: FilterPattern, exclude?: FilterPattern, options?: { resolve?: string | false | null }) => (id: string | unknown) => boolean;
140
141
/** File pattern matching type used by include/exclude options */
142
type FilterPattern = string | RegExp | Array<string | RegExp> | null;
143
```
144
145
### Include/Exclude Patterns
146
147
The `include` and `exclude` options accept:
148
- Single glob pattern: `"**/*.js"`
149
- Array of patterns: `["src/**/*.js", "lib/**/*.ts"]`
150
- Regular expressions: `/\.tsx?$/`
151
- Functions: `(id) => id.includes('src')`
152
153
### Custom File Reader
154
155
The `readFile` option allows customization of how files are loaded:
156
157
```typescript
158
sourcemaps({
159
readFile: (path, callback) => {
160
// Example: Add caching layer
161
if (cache.has(path)) {
162
callback(null, cache.get(path));
163
} else {
164
fs.readFile(path, (err, data) => {
165
if (!err) cache.set(path, data);
166
callback(err, data);
167
});
168
}
169
}
170
});
171
```
172
173
## Error Handling
174
175
The plugin handles various error conditions gracefully:
176
177
- **Failed file reads**: Issues a warning and delegates to the next plugin
178
- **Failed source map resolution**: Issues a warning and returns code without source map
179
- **Failed source content resolution**: Issues a warning but continues with the existing source map
180
181
All warnings are issued through Rollup's warning system and can be handled by the build configuration.
182
183
## Implementation Details
184
185
### Source Map Processing Pipeline
186
187
1. **File Filtering**: Uses `@rollup/pluginutils` to filter files based on include/exclude patterns
188
2. **Source Map Detection**: Scans file content for sourceMappingURL comments
189
3. **Source Map Resolution**: Loads external source map files using `source-map-resolve`
190
4. **Source Content Resolution**: Resolves missing source content when not included in source map
191
5. **Integration**: Returns combined code and source map data to Rollup
192
193
### Dependencies
194
195
The plugin internally uses:
196
- `@rollup/pluginutils`: For file filtering functionality
197
- `source-map-resolve`: For resolving source maps and source content
198
- Node.js `fs` module: For file system operations (unless custom `readFile` provided)
199
200
## Types
201
202
```typescript { .api }
203
/** Rollup source map representation */
204
interface ExistingRawSourceMap {
205
version: number;
206
sources: string[];
207
names: string[];
208
mappings: string;
209
file?: string;
210
sourceRoot?: string;
211
sourcesContent?: string[];
212
}
213
```