or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-source-map-loader

A webpack loader that extracts source maps from existing source files by reading their sourceMappingURL comments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/source-map-loader@5.0.x

To install, run

npx @tessl/cli install tessl/npm-source-map-loader@5.0.0

index.mddocs/

Source Map Loader

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.

Package Information

  • Package Name: source-map-loader
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install --save-dev source-map-loader

Core Imports

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:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: "pre",
        use: ["source-map-loader"],
      },
    ],
  },
};

Basic Usage

Simple Configuration

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: "pre",
        use: ["source-map-loader"],
      },
    ],
  },
};

With Options

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: "pre",
        use: [
          {
            loader: "source-map-loader",
            options: {
              filterSourceMappingUrl: (url, resourcePath) => {
                // Skip broken source maps
                if (/broken-source-map\.js$/i.test(url)) {
                  return false;
                }
                // Keep source mapping URLs for specific files
                if (/important-file\.js$/i.test(resourcePath)) {
                  return "skip";
                }
                return true; // Process normally
              },
            },
          },
        ],
      },
    ],
  },
};

Capabilities

Loader Function

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

/**
 * Main webpack loader function that extracts source maps from JavaScript files
 * This function operates within webpack's loader context
 * @param {string} input - The source code content
 * @param {object} inputMap - Existing input source map (optional)
 * @returns {void} - Uses webpack callback (this.async()) to return results asynchronously
 */
async function loader(input, inputMap);

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

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

Configuration Options

The loader accepts an options object with configuration settings.

interface LoaderOptions {
  /**
   * Function to control sourceMappingURL comment behavior
   * @param {string} sourceMappingURL - The URL from the sourceMappingURL comment
   * @param {string} resourcePath - Path to the current resource being processed
   * @returns {boolean | string} - Action to take for this source map
   */
  filterSourceMappingUrl?: (sourceMappingURL: string, resourcePath: string) => boolean | string;
}

Filter Source Mapping URL

Controls how the loader handles each sourceMappingURL comment it encounters.

/**
 * Filter function for controlling sourceMappingURL behavior
 * @param {string} sourceMappingURL - The URL extracted from sourceMappingURL comment
 * @param {string} resourcePath - Absolute path to the file being processed
 * @returns {boolean | string} - Action to take:
 *   - true or "consume": Process source map and remove comment (default)
 *   - false or "remove": Skip source map processing but remove comment
 *   - "skip": Skip source map processing and keep comment
 */
type FilterSourceMappingUrl = (sourceMappingURL: string, resourcePath: string) => boolean | "consume" | "remove" | "skip";

Usage Examples:

// Skip processing for specific URLs
filterSourceMappingUrl: (url, resourcePath) => {
  if (/broken-source-map\.js$/i.test(url)) {
    return false; // Remove comment but don't process
  }
  return true; // Process normally
}

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

Architecture

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

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

Error Handling

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

  • Missing or unreadable source map files
  • Invalid source map JSON
  • Broken data URLs
  • Network-related failures for remote URLs

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

Supported Source Map Formats

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

Node.js Requirements

  • Minimum Version: Node.js >= 18.12.0
  • Peer Dependencies: webpack ^5.72.1