or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

Gulp Sourcemaps

Gulp Sourcemaps provides comprehensive sourcemap support for Gulp.js build pipelines, enabling developers to maintain accurate debugging information and source references throughout the build process. It offers init() for initializing sourcemap tracking and write() for outputting sourcemaps either inline or as separate external files.

Package Information

  • Package Name: gulp-sourcemaps
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install gulp-sourcemaps

Core Imports

const sourcemaps = require('gulp-sourcemaps');

For individual function imports:

const { init, write, mapSources, identityMap } = require('gulp-sourcemaps');

Basic Usage

const gulp = require('gulp');
const sourcemaps = require('gulp-sourcemaps');
const uglify = require('gulp-uglify');

function javascript() {
  return gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())              // Initialize sourcemap tracking
    .pipe(uglify())                       // Transform with any gulp plugin
    .pipe(sourcemaps.write('.'))          // Write sourcemaps to same directory
    .pipe(gulp.dest('dist'));
}

exports.javascript = javascript;

Architecture

Gulp Sourcemaps integrates seamlessly with the Gulp ecosystem using transform streams:

  • Initialization: init() starts sourcemap tracking by creating empty sourcemaps or loading existing ones
  • Pipeline Integration: Works with any sourcemap-aware Gulp plugins between init() and write()
  • Output: write() handles both inline sourcemaps and external .map files
  • Utilities: mapSources and identityMap provide additional sourcemap manipulation capabilities

Capabilities

Sourcemap Initialization

Initialize sourcemap tracking at the beginning of a Gulp pipeline with support for loading existing sourcemaps and handling large files.

/**
 * Initialize source mapping chain for Gulp pipeline
 * @param {Object} options - Configuration options
 * @param {boolean} options.loadMaps - Load existing source maps from files, inline comments, or .map files
 * @param {boolean} options.identityMap - (Deprecated) Generate identity sourcemap instead of empty map
 * @param {boolean} options.largeFile - Handle large files efficiently
 * @returns {Transform} Transform stream for Gulp pipeline
 */
function init(options);

Usage Examples:

// Basic initialization
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(uglify())
  .pipe(sourcemaps.write())
  .pipe(gulp.dest('dist'));

// Load existing sourcemaps
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init({ loadMaps: true }))
  .pipe(babel())
  .pipe(sourcemaps.write())
  .pipe(gulp.dest('dist'));

// Handle large files
gulp.src('src/large-file.js')
  .pipe(sourcemaps.init({ largeFile: true }))
  .pipe(transform())
  .pipe(sourcemaps.write())
  .pipe(gulp.dest('dist'));

Sourcemap Output

Write sourcemaps either inline within source files or as separate external files with extensive configuration options for URLs, paths, and content inclusion.

/**
 * Write source map either inline or to external files
 * @param {string} destPath - Relative path for external source map files (optional, omit for inline)
 * @param {Object} options - Configuration options
 * @param {boolean} options.addComment - Add sourceMappingURL comment to files (default: true)
 * @param {boolean} options.includeContent - Include source content in sourcemap (default: true)  
 * @param {string|function} options.sourceRoot - Root path for source files
 * @param {string} options.destPath - Destination path for proper relative path calculation
 * @param {string} options.sourceMappingURLPrefix - Prefix for source map URLs
 * @param {function} options.sourceMappingURL - Custom function to generate source map URL
 * @param {string} options.charset - Character encoding (default: 'utf8')
 * @param {boolean} options.mapSourcesAbsolute - Map source paths to absolute paths
 * @returns {Transform} Transform stream for Gulp pipeline
 */
function write(destPath, options);

Usage Examples:

// Inline sourcemaps
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(uglify())
  .pipe(sourcemaps.write())              // Inline in the file
  .pipe(gulp.dest('dist'));

// External sourcemap files
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(uglify())
  .pipe(sourcemaps.write('../maps'))     // External .map files
  .pipe(gulp.dest('dist'));

// Advanced configuration
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(uglify())
  .pipe(sourcemaps.write('.', {
    addComment: false,                   // No sourceMappingURL comment
    includeContent: false,               // Don't include source content
    sourceRoot: '/src'                   // Set source root path
  }))
  .pipe(gulp.dest('dist'));

// Custom URL prefix
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(uglify())
  .pipe(sourcemaps.write('../maps', {
    sourceMappingURLPrefix: 'https://cdn.example.com/maps'
  }))
  .pipe(gulp.dest('dist'));

Source Path Mapping

Transform source paths in sourcemaps with full control over how source paths are resolved and referenced.

/**
 * Transform stream to alter the 'sources' property on sourcemaps  
 * @param {function} mapFn - Function to transform each source path
 * @returns {Transform} Transform stream for source path mapping
 */
function mapSources(mapFn);

Usage Examples:

// Prefix source paths
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(uglify())
  .pipe(sourcemaps.mapSources(function(sourcePath, file) {
    return '../src/' + sourcePath;
  }))
  .pipe(sourcemaps.write('../maps'))
  .pipe(gulp.dest('dist'));

// Transform to absolute URLs
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(uglify())
  .pipe(sourcemaps.mapSources(function(sourcePath, file) {
    return 'https://example.com/src/' + sourcePath;
  }))
  .pipe(sourcemaps.write())
  .pipe(gulp.dest('dist'));

Identity Sourcemap Generation

Generate a full valid identity sourcemap encoding no changes for JavaScript and CSS files when accurate mappings are needed for debugging.

/**
 * Generate full valid identity sourcemap with no changes (for JavaScript and CSS)
 * @returns {Transform} Transform stream for identity sourcemap generation
 */  
function identityMap();

Usage Examples:

// Generate identity sourcemap for accurate debugging
gulp.src('src/**/*.js')
  .pipe(sourcemaps.init())
  .pipe(sourcemaps.identityMap())        // Generate identity sourcemap
  .pipe(uglify())
  .pipe(sourcemaps.write('../maps'))
  .pipe(gulp.dest('dist'));

// Use with CSS files
gulp.src('src/**/*.css')
  .pipe(sourcemaps.init())
  .pipe(sourcemaps.identityMap())        // Identity map for CSS
  .pipe(autoprefixer())
  .pipe(sourcemaps.write())
  .pipe(gulp.dest('dist'));

Types

/**
 * Transform stream compatible with Gulp pipelines
 */
interface Transform {
  pipe(destination: Transform): Transform;
}

/**
 * Configuration for sourcemap initialization
 */
interface InitOptions {
  /** Load existing source maps from files, inline comments, or .map files */
  loadMaps?: boolean;
  /** (Deprecated) Generate identity sourcemap instead of empty map */
  identityMap?: boolean;
  /** Handle large files efficiently */
  largeFile?: boolean;
}

/**
 * Configuration for sourcemap output
 */
interface WriteOptions {
  /** Add sourceMappingURL comment to files (default: true) */
  addComment?: boolean;
  /** Include source content in sourcemap (default: true) */
  includeContent?: boolean;
  /** Root path for source files */
  sourceRoot?: string | ((file: any) => string);
  /** Destination path for proper relative path calculation */
  destPath?: string;
  /** Prefix for source map URLs */
  sourceMappingURLPrefix?: string;
  /** Custom function to generate source map URL */
  sourceMappingURL?: (file: any) => string;
  /** Character encoding (default: 'utf8') */
  charset?: string;
  /** Map source paths to absolute paths */
  mapSourcesAbsolute?: boolean;
}

/**
 * Function to transform source paths in sourcemaps
 */
type SourceMapFunction = (sourcePath: string, file: any) => string;