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:

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'))

Installation

$ npm i -D gulp-relative-sourcemaps-source

Usage

Update the source file paths in sourcemaps before you call sourcemaps.write:

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'))

Examples

Sample projects included in this module consist of two ES6 source files, which are minified by terser.

Project source hierarchy:

src/
  folder/
    file.js
  main.js

Separate Modules

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:

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:

dist/
  folder/
    file.js
    file.js.map
  main.js
  main.js.map

Content of the main.js.map file:

{
  "version": 3,
  "sources": ["main.js"],
  "names": [],
  "mappings": "...",
  "file": "main.js",
  "sourceRoot": "src"
}

Content of the file.js.map file:

{
  "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:

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:

{
  "version": 3,
  "sources": ["../src/main.js"],
  "names": [],
  "mappings": "...",
  "file": "main.js",
  "sourceRoot": "."
}

Updated content of the file.js.map file:

{
  "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:

{
  "cwd": ".",
  "sourceMaps": true,
  "outDir": "./dist"
}

Concatenated Modules

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:

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:

{
  "version": 3,
  "sources": [
    "../src/main.js",
    "../src/folder/file.js"
  ],
  "names": [],
  "mappings": "...",
  "file": "main.js",
  "sourceRoot": "."
}

API

relativeSourcemapsSource(options)

Returns a transform stream with a modified source file paths in sourceMap.sources. No other changes.

options

Type: object

options.dest

Type: string Default: undefined

Root output directory to write the transpiled files to. Mandatory.

Release History

• 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.

License

MIT © 2015-2019 Ferdinand Prantl