or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-rollup-plugin-sourcemaps

Rollup plugin for grabbing source maps from sourceMappingURLs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/rollup-plugin-sourcemaps@0.6.x

To install, run

npx @tessl/cli install tessl/npm-rollup-plugin-sourcemaps@0.6.0

index.mddocs/

Rollup Plugin Sourcemaps

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.

Package Information

  • Package Name: rollup-plugin-sourcemaps
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install rollup-plugin-sourcemaps

Core Imports

import sourcemaps from "rollup-plugin-sourcemaps";
import type { SourcemapsPluginOptions } from "rollup-plugin-sourcemaps";
import type { Plugin } from "rollup";
import type { CreateFilter } from "@rollup/pluginutils";

For CommonJS:

const sourcemaps = require("rollup-plugin-sourcemaps");

Basic Usage

import sourcemaps from "rollup-plugin-sourcemaps";

export default {
  input: 'src/index.js',
  plugins: [sourcemaps()],
  output: {
    sourcemap: true,
    file: 'dist/bundle.js',
  },
};

With options:

import sourcemaps from "rollup-plugin-sourcemaps";

export default {
  input: 'src/index.js',
  plugins: [
    sourcemaps({
      include: '**/*.js',
      exclude: 'node_modules/**',
    })
  ],
  output: {
    sourcemap: true,
    file: 'dist/bundle.js',
  },
};

Capabilities

Plugin Factory Function

Creates a Rollup plugin instance for handling source maps in the build process.

/**
 * Creates a Rollup plugin for loading files with existing source maps
 * @param options - Optional configuration for the plugin
 * @returns Rollup plugin instance
 */
export default function sourcemaps(options?: SourcemapsPluginOptions): Plugin;

The returned plugin implements the Rollup Plugin interface:

interface Plugin {
  /** Plugin identifier */
  name: string;
  /** 
   * Processes files and their source maps during the load phase
   * @param id - File identifier/path being loaded
   * @returns Promise resolving to null (delegate to next plugin), code string, or code with source map
   */
  load(id: string): Promise<null | string | { code: string; map: ExistingRawSourceMap }>;
}

Usage Examples:

// Basic usage with no options
const plugin = sourcemaps();

// With file filtering
const plugin = sourcemaps({
  include: ['src/**/*.js', 'lib/**/*.ts'],
  exclude: ['**/*.test.js']
});

// With custom file reader
const plugin = sourcemaps({
  readFile: (path, callback) => {
    // Custom file reading logic
    fs.readFile(path, callback);
  }
});

Plugin Options

export interface SourcemapsPluginOptions {
  /** 
   * Pattern or array of patterns to include files for source map processing
   * Uses the same format as @rollup/pluginutils createFilter
   */
  include?: Parameters<CreateFilter>[0];
  
  /** 
   * Pattern or array of patterns to exclude files from source map processing
   * Uses the same format as @rollup/pluginutils createFilter
   */
  exclude?: Parameters<CreateFilter>[1];
  
  /** 
   * Custom file reading function for loading source files and source maps
   * Defaults to fs.readFile if not provided
   */
  readFile?(
    path: string, 
    callback: (error: Error | null, data: Buffer | string) => void
  ): void;
}

/** Type alias for the CreateFilter function from @rollup/pluginutils */
type CreateFilter = (include?: FilterPattern, exclude?: FilterPattern, options?: { resolve?: string | false | null }) => (id: string | unknown) => boolean;

/** File pattern matching type used by include/exclude options */
type FilterPattern = string | RegExp | Array<string | RegExp> | null;

Include/Exclude Patterns

The include and exclude options accept:

  • Single glob pattern: "**/*.js"
  • Array of patterns: ["src/**/*.js", "lib/**/*.ts"]
  • Regular expressions: /\.tsx?$/
  • Functions: (id) => id.includes('src')

Custom File Reader

The readFile option allows customization of how files are loaded:

sourcemaps({
  readFile: (path, callback) => {
    // Example: Add caching layer
    if (cache.has(path)) {
      callback(null, cache.get(path));
    } else {
      fs.readFile(path, (err, data) => {
        if (!err) cache.set(path, data);
        callback(err, data);
      });
    }
  }
});

Error Handling

The plugin handles various error conditions gracefully:

  • Failed file reads: Issues a warning and delegates to the next plugin
  • Failed source map resolution: Issues a warning and returns code without source map
  • Failed source content resolution: Issues a warning but continues with the existing source map

All warnings are issued through Rollup's warning system and can be handled by the build configuration.

Implementation Details

Source Map Processing Pipeline

  1. File Filtering: Uses @rollup/pluginutils to filter files based on include/exclude patterns
  2. Source Map Detection: Scans file content for sourceMappingURL comments
  3. Source Map Resolution: Loads external source map files using source-map-resolve
  4. Source Content Resolution: Resolves missing source content when not included in source map
  5. Integration: Returns combined code and source map data to Rollup

Dependencies

The plugin internally uses:

  • @rollup/pluginutils: For file filtering functionality
  • source-map-resolve: For resolving source maps and source content
  • Node.js fs module: For file system operations (unless custom readFile provided)

Types

/** Rollup source map representation */
interface ExistingRawSourceMap {
  version: number;
  sources: string[];
  names: string[];
  mappings: string;
  file?: string;
  sourceRoot?: string;
  sourcesContent?: string[];
}