Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/prantlf/gulp-relative-sourcemaps-source
Enables debugging of "babelified" scripts by converting source paths in sourcemaps to be relative to the output file directories
https://github.com/prantlf/gulp-relative-sourcemaps-source
gulp sourcemaps
Last synced: 2 months ago
JSON representation
Enables debugging of "babelified" scripts by converting source paths in sourcemaps to be relative to the output file directories
- Host: GitHub
- URL: https://github.com/prantlf/gulp-relative-sourcemaps-source
- Owner: prantlf
- License: mit
- Created: 2015-12-29T23:57:09.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2019-11-02T06:39:59.000Z (over 5 years ago)
- Last Synced: 2024-11-15T21:34:14.249Z (3 months ago)
- Topics: gulp, sourcemaps
- Language: JavaScript
- Homepage:
- Size: 293 KB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gulp-relative-sourcemaps-source
[](http://badge.fury.io/js/gulp-relative-sourcemaps-source)
[](https://travis-ci.org/prantlf/gulp-relative-sourcemaps-source)
[](https://david-dm.org/prantlf/gulp-relative-sourcemaps-source)
[](https://david-dm.org/prantlf/gulp-relative-sourcemaps-source#info=devDependencies)
> Convert paths to files with the sourcemaps content to be relative to the output file directories
[](https://www.npmjs.com/package/gulp-relative-sourcemaps-source)
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'))
```
## Installation
```
$ npm i -D gulp-relative-sourcemaps-source
```
## Usage
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'))
```
## Examples
[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
```
### 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:
```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"
}
```
### 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:
```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": "."
}
```
## 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](http://prantl.tk)
[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