gulp-sourcemaps
Usage
Write inline source maps
Inline source maps are embedded in the source file.
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
});
All plugins between sourcemaps.init()
and sourcemaps.write()
need to have support for gulp-sourcemaps
. You can find a list of such plugins in the wiki.
Write 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 plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps'))
.pipe(gulp.dest('dist'));
});
Load existing source maps
To load existing source maps, pass the option loadMaps: true
to sourcemaps.init()
.
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init({loadMaps: true}))
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
});
Handle source files from different directories
Use the base
option on gulp.src
to make sure all files are relative to a common base directory.
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
gulp.task('javascript', function() {
gulp.src(['src/test.js', 'src/testdir/test2.js'], { base: 'src' })
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps'))
.pipe(gulp.dest('dist'));
});
Init Options
Write 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(plugin1())
.pipe(plugin2())
.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, or define it with a function.
Example:
gulp.task('javascript', function() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write({includeContent: false, sourceRoot: '/src'}))
.pipe(gulp.dest('dist'));
});
Example (using a function):
gulp.task('javascript', function() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write({
includeContent: false,
sourceRoot: function(file) {
return '/src';
}
}))
.pipe(gulp.dest('dist'));
});
-
sourceMappingURLPrefix
Specify a prefix to be prepended onto the source map URL when writing external source maps. Relative paths will have their leading dots stripped.
Example:
gulp.task('javascript', function() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps', {
sourceMappingURLPrefix: 'https://asset-host.example.com/assets'
}))
.pipe(gulp.dest('public/scripts'));
});
This will result in a source mapping URL comment like sourceMappingURL=https://asset-host.example.com/assets/maps/helloworld.js.map
.
-
sourceMappingURL
If you need full control over the source map URL you can pass a function to this option. The output of the function must be the full URL to the source map (in function of the output file).
Example:
gulp.task('javascript', function() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps', {
sourceMappingURL: function(file) {
return 'https://asset-host.example.com/' + file.relative + '.map';
}
}))
.pipe(gulp.dest('public/scripts'));
});
This will result in a source mapping URL comment like sourceMappingURL=https://asset-host.example.com/helloworld.js.map
.
-
debug
Set this to true
to output debug messages (e.g. about missing source content).
Plugin developers only: How to add source map support to plugins
- Generate a source map for the transformation the plugin is applying
- Important: Make sure the paths in the generated source map (
file
and sources
) are relative to file.base
(e.g. use file.relative
). - 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. - Add your plugin to the wiki page
Example:
var through = require('through2');
var applySourceMap = require('vinyl-sourcemaps-apply');
var myTransform = require('myTransform');
module.exports = function(options) {
function transform(file, encoding, callback) {
if (file.sourceMap) {
options.makeSourceMaps = true;
}
var result = myTransform(file.contents, options);
file.contents = new Buffer(result.code);
if (file.sourceMap) {
applySourceMap(file, result.map);
}
this.push(file);
callback();
}
return through.obj(transform);
};