Converts paths to files with the sourcemaps content to be relative to the source file directory.
npm install gulp-relative-sourcemaps-source> Convert paths to files with the sourcemaps content to be relative to the output file directories
Enables debugging in IDEs like WebStorm or VSCode with sourcemaps generated by gulp-sourcemaps either for a web browser or for a Node.js application transpiled by babel. These IDEs ignore inline sourcemaps content and are able to read the original source files only if their paths are relative to the output file directories.
For gulp-sourcemaps >= 1.7.0 users: You do not need this plugin any more. gulp-sourcemaps < 1.7.0 did not adapt sourceRoot in source maps dynamically for every file according to the relative source path, but the newer gulp-sourcemaps does it, if you specify sourceRoot as a relative path. If you use this plugin with the newer gulp-sourcemaps, you will need to consider both sources[] and sourceRoot contributing to the full path, which is the least problematic if you set sourceRoot to ".". You might find still a usage scenario, which require this plugin with gulp-sourcemaps >= 1.7.0, if you specify sourceRoot as an absolute path.
The following code performs the same a the example below, but without gulp-relative-sourcemaps-source and using gulp-sourcemaps >= 1.7.0:
`js`
gulp.src(['src/*/.js'])
.pipe(sourcemaps.init())
.pipe(babel())
// Remove relativeSourcemapsSource used for sourcemaps 1
//.pipe(relativeSourcemapsSource({ dest: 'dist' }))
.pipe(sourcemaps.write('.', {
includeContent: false,
// Change '.' used with relativeSourcemapsSource to '../src';
// sourcemaps 2 will make paths of dist/*/.js relative to
// the directory you get from dist to - to src
sourceRoot: '../src'
}))
.pipe(gulp.dest('dist'))
`
$ npm i -D gulp-relative-sourcemaps-source
Update the source file paths in sourcemaps before you call sourcemaps.write:
`js`
const babel = require('gulp-babel')
const sourcemaps = require('gulp-sourcemaps')
const relativeSourcemapsSource = require('gulp-relative-sourcemaps-source')
// Pass the base directory for the source files
gulp.src(['src/*/.js'])
.pipe(sourcemaps.init())
.pipe(babel())
// Pass the same directory as passed to gulp.dest()
.pipe(relativeSourcemapsSource({ dest: 'dist' }))
// Write sourcemaps to the same directory as the transpiled files are
// written to and do not let the sourceRoot affect the relative path
.pipe(sourcemaps.write('.', {
includeContent: false,
sourceRoot: '.'
}))
.pipe(gulp.dest('dist'))
[Sample projects] included in this module consist of two ES6 source files, which are minified by terser.
Project source hierarchy:
`text`
src/
folder/
file.js
main.js
[This example] leaves the distribution file structure the same as the source file structure to keep output file changes at minimum during development.
Gulp build task:
`js`
const babel = require('gulp-babel')
const sourcemaps = require('gulp-sourcemaps')
return gulp.src(['src/*/.js'])
.pipe(sourcemaps.init())
.pipe(babel())
.pipe(sourcemaps.write('.', {
includeContent: false,
sourceRoot: 'src'
}))
.pipe(gulp.dest('dist'))
Build output hierarchy:
`text`
dist/
folder/
file.js
file.js.map
main.js
main.js.map
Content of the main.js.map file:
`json`
{
"version": 3,
"sources": ["main.js"],
"names": [],
"mappings": "...",
"file": "main.js",
"sourceRoot": "src"
}
Content of the file.js.map file:
`json`
{
"version": 3,
"sources": ["folder/file.js"],
"names": [],
"mappings": "...",
"file": "folder/file.js",
"sourceRoot": "src"
}
Although it would appear that the path made of sourceRoot and sources[0] parts, which points to source files when taking the project root as the root directory, should be usable by the debuggers, they will fail to find the source files. Apparently they do not look for the source files starting in the project root. Using an absolute source base directory for sourceRoot does not help, for example: "sourceRoot": "/src". What helps, is making the combination of sourceRoot and sources[0] relative to the output directory of the particular file.
Updated Gulp build task:
`js`
const babel = require('gulp-babel')
const sourcemaps = require('gulp-sourcemaps')
const relativeSourcemapsSource = require('gulp-relative-sourcemaps-source')
return gulp.src(['src/*/.js'])
.pipe(sourcemaps.init())
.pipe(babel())
.pipe(relativeSourcemapsSource({dest: 'dist'}))
.pipe(sourcemaps.write('.', {
includeContent: false,
sourceRoot: '.'
}))
.pipe(gulp.dest('dist'))
Updated content of the main.js.map file:
`json`
{
"version": 3,
"sources": ["../src/main.js"],
"names": [],
"mappings": "...",
"file": "main.js",
"sourceRoot": "."
}
Updated content of the file.js.map file:
`json`
{
"version": 3,
"sources": ["../../src/folder/file.js"],
"names": [],
"mappings": "...",
"file": "folder/file.js",
"sourceRoot": "."
}
WebStorm debugger will use the correct source files right away. VSCode will need the following settings in the launch configuration:
`json`
{
"cwd": ".",
"sourceMaps": true,
"outDir": "./dist"
}
Modern applications concatenate and minify source modules to a single or multiple bundles even for development/debugging pages. This plugin supports this scenario roo. Just make sure, that you enable source maps, before you concatenate files for the bundles. [Another example] shows how to configure a project with gulp and rollup.
Gulp build task:
`js`
const rollup = require('rollup-stream')
const babel = require('gulp-babel')
const buffer = require('vinyl-buffer')
const source = require('vinyl-source-stream')
const sourcemaps = require('gulp-sourcemaps')
const relativeSourcemapsSource = require('gulp-relative-sourcemaps-source')
return rollup({
input: 'src/main.js',
sourcemap: true
})
.pipe(source('main.js', './src'))
.pipe(buffer())
.pipe(sourcemaps.init({ loadMaps: true }))
.pipe(babel())
.pipe(relativeSourcemapsSource({ dest: 'dist' }))
.pipe(sourcemaps.write('.', {
includeContent: false,
sourceRoot: '.'
}))
.pipe(gulp.dest('dist'))
Content of the main.js.map file:
`json`
{
"version": 3,
"sources": [
"../src/main.js",
"../src/folder/file.js"
],
"names": [],
"mappings": "...",
"file": "main.js",
"sourceRoot": "."
}
Returns a [transform stream] with a modified source file paths in sourceMap.sources. No other changes.
#### options
Type: object
#### options.dest
Type: string
Default:
Root output directory to write the transpiled files to. Mandatory.
* 2019-06-08 v1.1.0 Support for output module bundles concatenated
from multiple source files
* 2018-04-27 v1.0.0 Dropped support of Node.js 4
* 2016-12-21 v0.1.5 Add example, update dependencies
* 2016-10-02 v0.1.4 Fix running with an empty array of source map sources
* 2016-26-08 v0.1.3 Upgrade dependencies
* 2016-02-01 v0.1.2 Fix transpiling files with other file extension;
.ts to .js with TypeScript, for example.
* 2015-12-30 v0.1.1 Initial release.
MIT © 2015-2019 Ferdinand Prantl
[Sample projects]: ./examples
[This example]: ./examples/separate-files
[Another example]: ./examples/concatenated-files
[transform stream]: http://nodejs.org/api/stream.html#stream_class_stream_transform