Research
Security News
Malicious npm Package Targets Solana Developers and Hijacks Funds
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
gulp-sourcemaps
Advanced tools
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.
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'));
});
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.
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.
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.
Sourcemap support for gulpjs.
All the examples here works with Gulp 4. To see examples related to Gulp 3, you can read them here.
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');
function javascript() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
};
exports.javascript = javascript;
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.
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');
function javascript() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps'))
.pipe(gulp.dest('dist'));
};
exports.javascript = javascript;
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');
function javascript() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init({loadMaps: true}))
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
};
exports.javascript = javascript;
To handle large files, pass the option largeFile: true
to sourcemaps.init()
.
Example:
var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');
function javascript() {
gulp.src('src/**/*.js')
.pipe(sourcemaps.init({largeFile: true}))
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write())
.pipe(gulp.dest('dist'));
};
exports.javascript = javascript;
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');
function javascript() {
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'));
};
exports.javascript = javascript;
sources
property on sourcemapsThe exported mapSources
method gives full control over the source paths. It takes a function that is called for every source and receives the default source path as a parameter and the original vinyl file.
Example:
function javascript() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
// be careful with the sources returned otherwise contents might not be loaded properly
.pipe(sourcemaps.mapSources(function(sourcePath, file) {
// source paths are prefixed with '../src/'
return '../src/' + sourcePath;
}))
.pipe(sourcemaps.write('../maps')
.pipe(gulp.dest('public/scripts'));
};
exports.javascript = javascript;
The exported identityMap
method allows you to generate a full valid source map encoding no changes (slower, only for Javascript and CSS) instead of the default empty source map (no mappings, fast). Use this option if you get missing or incorrect mappings, e.g. when debugging.
Example:
function javascript() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
// An identity sourcemap will be generated at this step
.pipe(sourcemaps.identityMap())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps')
.pipe(gulp.dest('public/scripts'));
};
exports.javascript = javascript;
loadMaps
Set to true to load existing maps for source files. Supports the following:
sourceMappingURL=
commentidentityMap
This option is deprecated. Upgrade to use our sourcemap.identityMap
API.
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:
function javascript() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps', {addComment: false}))
.pipe(gulp.dest('dist'));
};
exports.javascript = javascript;
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 location where the source files are hosted (use this when includeContent
is set to false
). This is usually a URL (or an absolute URL path), not a local file system path.
By default the source root is '' or in case destPath
is set, the relative path from the source map to the source base directory (this should work for many dev environments).
If a relative path is used (empty string or one starting with a .
), it is interpreted as a path relative to the destination. The plugin rewrites it to a path relative to each source map.
Example:
function javascript() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write({includeContent: false, sourceRoot: '/src'}))
.pipe(gulp.dest('dist'));
};
exports.javascript = javascript;
Example (using a function):
function javascript() {
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'));
};
exports.javascript = javascript;
Example (relative path):
function javascript() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('.', {includeContent: false, sourceRoot: '../src'}))
.pipe(gulp.dest('dist'));
};
exports.javascript = javascript;
In this case for a file written to dist/subdir/example.js
, the source map is written to dist/subdir/example.js.map
and the sourceRoot will be ../../src
(resulting in the full source path ../../src/subdir/example.js
).
destPath
Set the destination path (the same you pass to gulp.dest()
). If the source map destination path is not a sub path of the destination path, this is needed to get the correct path in the file
property of the source map.
In addition, it allows to automatically set a relative sourceRoot
if none is set explicitly.
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:
function javascript() {
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'));
};
exports.javascript = javascript;
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:
function javascript() {
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'));
};
exports.javascript = javascript;
This will result in a source mapping URL comment like sourceMappingURL=https://asset-host.example.com/helloworld.js.map
.
mapFile
This option allows to rename the map file. It takes a function that is called for every map and receives the default map path as a parameter.
Example:
function javascript() {
var stream = gulp.src('src/**/*.js')
.pipe(sourcemaps.init())
.pipe(plugin1())
.pipe(plugin2())
.pipe(sourcemaps.write('../maps', {
mapFile: function(mapFilePath) {
// source map files are named *.map instead of *.js.map
return mapFilePath.replace('.js.map', '.map');
}
}))
.pipe(gulp.dest('public/scripts'));
};
exports.javascript = javascript;
mapSources
This option is deprecated. Upgrade to use our sourcemap.mapSources
API.
charset
Sets the charset for inline source maps. Default: utf8
clone
Clones the original file for creation of the map file. Could be important if file history is important. See file.clone() for possible options. Default: {deep:false, contents:false}
How to add source map support to plugins
file
and sources
) are relative to file.base
(e.g. use file.relative
).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.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);
};
Verify sourcemaps are working
See example below or refer to test/write.js
var stream = plugin();
var init = sourcemaps.init();
var write = sourcemaps.write();
init.pipe(stream).pipe(write);
write.on('data', function (file) {
assert(...);
cb();
});
init.write(new gutil.File(...));
init.end();
All debugging output relies on visionmedia/debug. Follow the directions to set the
environment variable $DEBUG
.
For a few examples of debug you could use:
DEBUG='gulp-sourcemaps:*' #everything
DEBUG='gulp-sourcemaps:init' #init/index.js
DEBUG='gulp-sourcemaps:init:*' #init/index.internals.js
DEBUG='gulp-sourcemaps:write:' #write/index.js
DEBUG='gulp-sourcemaps:write:*' #write/index.internals.js
DEBUG='gulp-sourcemaps:write:,gulp-sourcemaps:init:**' #write/index.internals.js and init/index.internals.js
FAQs
Sourcemap support for gulpjs.
The npm package gulp-sourcemaps receives a total of 528,123 weekly downloads. As such, gulp-sourcemaps popularity was classified as popular.
We found that gulp-sourcemaps demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.