0
# Source Map Loader
1

2
Source Map Loader is a webpack loader that extracts source maps from existing source files by reading their sourceMappingURL comments. It handles both inline source maps and those linked via URL, processing all source map data and passing it to webpack for integration into the final bundle's source map.
3

4
## Package Information
5

6
- **Package Name**: source-map-loader
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev source-map-loader`
10

11
## Core Imports
12

13
This package is used as a webpack loader, so it's not imported directly in application code. Instead, it's configured in your webpack configuration:
14

15
```javascript
16
// webpack.config.js
17
module.exports = {
18
  module: {
19
    rules: [
20
      {
21
        test: /\.js$/,
22
        enforce: "pre",
23
        use: ["source-map-loader"],
24
      },
25
    ],
26
  },
27
};
28
```
29

30
## Basic Usage
31

32
### Simple Configuration
33

34
```javascript
35
// webpack.config.js
36
module.exports = {
37
  module: {
38
    rules: [
39
      {
40
        test: /\.js$/,
41
        enforce: "pre",
42
        use: ["source-map-loader"],
43
      },
44
    ],
45
  },
46
};
47
```
48

49
### With Options
50

51
```javascript
52
// webpack.config.js
53
module.exports = {
54
  module: {
55
    rules: [
56
      {
57
        test: /\.js$/,
58
        enforce: "pre",
59
        use: [
60
          {
61
            loader: "source-map-loader",
62
            options: {
63
              filterSourceMappingUrl: (url, resourcePath) => {
64
                // Skip broken source maps
65
                if (/broken-source-map\.js$/i.test(url)) {
66
                  return false;
67
                }
68
                // Keep source mapping URLs for specific files
69
                if (/important-file\.js$/i.test(resourcePath)) {
70
                  return "skip";
71
                }
72
                return true; // Process normally
73
              },
74
            },
75
          },
76
        ],
77
      },
78
    ],
79
  },
80
};
81
```
82

83
## Capabilities
84

85
### Loader Function
86

87
The main webpack loader function that processes JavaScript files to extract source maps.
88

89
```javascript { .api }
90
/**
91
 * Main webpack loader function that extracts source maps from JavaScript files
92
 * This function operates within webpack's loader context
93
 * @param {string} input - The source code content
94
 * @param {object} inputMap - Existing input source map (optional)
95
 * @returns {void} - Uses webpack callback (this.async()) to return results asynchronously
96
 */
97
async function loader(input, inputMap);
98
```
99

100
The loader is designed to be used in webpack's module processing pipeline. It:
101

102
1. Searches for `sourceMappingURL` comments in the input code
103
2. Fetches the referenced source map (from URLs, file paths, or inline data URLs)
104
3. Processes and resolves all source files referenced in the source map
105
4. Calls webpack's async callback with the cleaned input code and processed source map
106
5. Adds source map files as webpack dependencies for watch mode
107
6. Emits warnings for failed operations while allowing builds to continue
108

109
### Configuration Options
110

111
The loader accepts an options object with configuration settings.
112

113
```javascript { .api }
114
interface LoaderOptions {
115
  /**
116
   * Function to control sourceMappingURL comment behavior
117
   * @param {string} sourceMappingURL - The URL from the sourceMappingURL comment
118
   * @param {string} resourcePath - Path to the current resource being processed
119
   * @returns {boolean | string} - Action to take for this source map
120
   */
121
  filterSourceMappingUrl?: (sourceMappingURL: string, resourcePath: string) => boolean | string;
122
}
123
```
124

125
#### Filter Source Mapping URL
126

127
Controls how the loader handles each sourceMappingURL comment it encounters.
128

129
```javascript { .api }
130
/**
131
 * Filter function for controlling sourceMappingURL behavior
132
 * @param {string} sourceMappingURL - The URL extracted from sourceMappingURL comment
133
 * @param {string} resourcePath - Absolute path to the file being processed
134
 * @returns {boolean | string} - Action to take:
135
 *   - true or "consume": Process source map and remove comment (default)
136
 *   - false or "remove": Skip source map processing but remove comment
137
 *   - "skip": Skip source map processing and keep comment
138
 */
139
type FilterSourceMappingUrl = (sourceMappingURL: string, resourcePath: string) => boolean | "consume" | "remove" | "skip";
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
// Skip processing for specific URLs
146
filterSourceMappingUrl: (url, resourcePath) => {
147
  if (/broken-source-map\.js$/i.test(url)) {
148
    return false; // Remove comment but don't process
149
  }
150
  return true; // Process normally
151
}
152

153
// Keep source mapping URLs for debugging
154
filterSourceMappingUrl: (url, resourcePath) => {
155
  if (/debug-build\.js$/i.test(resourcePath)) {
156
    return "skip"; // Keep comment and don't process
157
  }
158
  return "consume"; // Process and remove comment
159
}
160
```
161

162
## Architecture
163

164
Source Map Loader operates as a pre-processing webpack loader with the following key components:
165

166
- **Source Map Detection**: Regex-based detection of sourceMappingURL comments in JavaScript files
167
- **URL Resolution**: Handles various URL formats including data URLs, file URLs, relative paths, and absolute paths
168
- **File System Integration**: Uses webpack's file system abstraction for reading source map files
169
- **Dependency Tracking**: Automatically adds source map files as webpack dependencies
170
- **Error Handling**: Emits warnings for failed operations while allowing the build to continue
171
- **Character Encoding**: Supports multiple character encodings via iconv-lite
172

173
## Error Handling
174

175
The loader is designed to be fault-tolerant and will emit webpack warnings (not errors) for:
176

177
- Missing or unreadable source map files
178
- Invalid source map JSON
179
- Broken data URLs
180
- Network-related failures for remote URLs
181

182
This ensures that builds continue even when source maps are problematic, while still providing visibility into issues through webpack's warning system.
183

184
## Supported Source Map Formats
185

186
- **Inline source maps**: Data URLs embedded in sourceMappingURL comments
187
- **External source maps**: File references via relative or absolute paths
188
- **File URLs**: References using file:// protocol
189
- **Indexed source maps**: Multi-section source maps (automatically flattened)
190
- **Various encodings**: UTF-8, ISO-8859-*, Windows-*, and many others via iconv-lite
191

192
## Node.js Requirements
193

194
- **Minimum Version**: Node.js >= 18.12.0
195
- **Peer Dependencies**: webpack ^5.72.1