gulp-sourcemaps

What is gulp-sourcemaps?

The gulp-sourcemaps package is a plugin for Gulp that allows you to generate source maps for your files. Source maps are files that map from the transformed source to the original source, enabling you to debug your code more easily by seeing the original source in your browser's developer tools.

What are gulp-sourcemaps's main functionalities?

Initialize Source Maps

This feature initializes the source map generation process. The `sourcemaps.init()` method is called before any transformations are applied to the files, and `sourcemaps.write('.')` writes the source maps to the same directory as the transformed files.

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

gulp.task('default', function () {
  return gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest('dist'));
});

Write Inline Source Maps

This feature writes the source maps inline within the transformed files. The `sourcemaps.write()` method without any arguments will embed the source map directly into the output file.

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

gulp.task('default', function () {
  return gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())
    .pipe(sourcemaps.write())
    .pipe(gulp.dest('dist'));
});

Custom Source Map Path

This feature allows you to specify a custom path for the source maps. The `sourcemaps.write('../maps')` method writes the source maps to a directory named 'maps' that is one level up from the output directory.

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

gulp.task('default', function () {
  return gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())
    .pipe(sourcemaps.write('../maps'))
    .pipe(gulp.dest('dist'));
});

Other packages similar to gulp-sourcemaps

gulp-sourcemap

The gulp-sourcemap package is another plugin for generating source maps in Gulp. It is similar to gulp-sourcemaps but is less popular and has fewer features. It is a simpler alternative for basic source map generation needs.

gulp-babel

The gulp-babel package is primarily used for transpiling JavaScript using Babel, but it also has built-in support for generating source maps. It is a good choice if you are already using Babel for transpilation and want to generate source maps as part of the same process.

gulp-uglify

The gulp-uglify package is used for minifying JavaScript files. It can also generate source maps for the minified files. It is useful if you want to combine minification and source map generation in a single step.

README

gulp-sourcemaps

Usage

Inline maps

Inline maps are embedded in the source file.

var gulp = require('gulp');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var sourcemaps = require('gulp-sourcemaps');

gulp.task('javascript', function() {
  gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())
      .pipe(concat('all.js'))
      .pipe(uglify())
    .pipe(sourcemaps.write())
    .pipe(gulp.dest('dist'));
});

All plugins between sourcemaps.init() and sourcemaps.write() need to support source maps.

Warning: the current NPM version of gulp-concat doesn't support source maps yet. You can use https://github.com/floridoo/gulp-concat/tree/sourcemap_pipe2 for now.

External source map files

To write external source map files, pass a path relative to the destination to sourcemaps.write().

Example:

var gulp = require('gulp');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var sourcemaps = require('gulp-sourcemaps');

gulp.task('javascript', function() {
  gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())
      .pipe(concat('all.js'))
      .pipe(uglify())
    .pipe(sourcemaps.write('../maps'))
    .pipe(gulp.dest('dist'));
});

Options

• addComment

  By default a comment containing / referencing the source map is added. Set this to false to disable the comment (e.g. if you want to load the source maps by header).

  Example:

  gulp.task('javascript', function() {
    var stream = gulp.src('src/**/*.js')
      .pipe(sourcemaps.init())
        .pipe(concat('all.js'))
        .pipe(uglify())
      .pipe(sourcemaps.write('../maps', {addComment: false}))
      .pipe(gulp.dest('dist'));
  });
  

• includeContent

  By default the source maps include the source code. Pass false to use the original files.

• sourceRoot

  Set the path where the source files are hosted (use this when includeContent is set to false).

  Example:

  gulp.task('javascript', function() {
    var stream = gulp.src('src/**/*.js')
      .pipe(sourcemaps.init())
        .pipe(concat('all.js'))
        .pipe(uglify())
      .pipe(sourcemaps.write({includeContent: false, sourceRoot: '/src'}))
      .pipe(gulp.dest('dist'));
  });
  

Plugin developers only: How to add source map support to plugins

• Generate a source map for the transformation the plugin is applying
• Apply this source map to the vinyl file. E.g. by using vinyl-sourcemaps-apply. This combines the source map of this plugin with the source maps coming from plugins further up the chain.

Example:

var through = require('through2');
var applySourceMap = require('vinyl-sourcemaps-apply');
var myTransform = require('myTransform');

module.exports = function(options) {

  function transform(file, encoding, callback) {
    // generate source maps if plugin source-map present
    if (file.sourceMap) {
      options.makeSourceMaps = true;
    }

    // do normal plugin logic
    var result = myTransform(file.contents, options);
    file.contents = new Buffer(result.code);

    // apply source map to the chain
    if (file.sourceMap) {
      applySourceMap(file, result.map);
    }

    this.push(file);
    callback();
  }

  return through.obj(transform);
};