JSPM

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.

  Including the content is the recommended way, because it "just works". When setting this to false you have to host the source files and set the correct sourceRoot.

• sourceRoot

  Set the path where the source files are hosted (use this when includeContent is set to false). This is an URL (or subpath) relative to the source map, not a local file system path. If you have sources in different subpaths, an absolute path (from the domain root) pointing to the source file root is recommended.

  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);
};