combine-source-map

What is combine-source-map?

The combine-source-map npm package is used to create and modify source maps, which are files that map from the transformed source to the original source, allowing developers to debug their code more easily. This package is particularly useful when dealing with multiple source files that need to be combined into a single file, while still maintaining accurate source maps.

What are combine-source-map's main functionalities?

Create a new source map

This feature allows you to create a new source map for a given file. In this example, a new source map is created for 'bundle.js'.

const combine = require('combine-source-map');
const map = combine.create('bundle.js');
console.log(map);

Add a file to the source map

This feature allows you to add a file to the source map. In this example, 'file1.js' is added to the source map with its content and starting line number.

const combine = require('combine-source-map');
const map = combine.create('bundle.js');
map.addFile({ sourceFile: 'file1.js', source: 'console.log("file1");' }, { line: 0 });
console.log(map);

Generate the source map

This feature allows you to generate the source map in base64 format. In this example, after adding 'file1.js' to the source map, the source map is generated and logged in base64 format.

const combine = require('combine-source-map');
const map = combine.create('bundle.js');
map.addFile({ sourceFile: 'file1.js', source: 'console.log("file1");' }, { line: 0 });
const sourceMap = map.base64();
console.log(sourceMap);

Other packages similar to combine-source-map

source-map

The source-map package provides a library for generating and consuming source maps. It offers more granular control over source map generation and manipulation compared to combine-source-map, making it suitable for more complex use cases.

gulp-sourcemaps

The gulp-sourcemaps package is a plugin for Gulp that simplifies the process of generating and working with source maps in a Gulp build pipeline. It is more integrated with the Gulp ecosystem, making it a better choice for projects that use Gulp for task automation.

webpack

Webpack is a module bundler that includes built-in support for source maps. It provides a comprehensive solution for bundling JavaScript applications, including source map generation, making it a more feature-rich but complex alternative to combine-source-map.

README

combine-source-map

Add source maps of multiple files, offset them and then combine them into one source map.

var convert = require('convert-source-map');
var combine = require('combine-source-map');

var fooComment = '//@ sourceMappingURL=data:application/json;base64,eyJ2Z [..] pzJylcbiJdfQ==';
var barComment = '//@ sourceMappingURL=data:application/json;base64,eyJ2Z [..] VjaycpXG4iXX0=';

var fooFile = {
    source: '(function() {\n\n  console.log(require(\'./bar.js\'));\n\n}).call(this);\n' + '\n' + fooComment
  , sourceFile: 'foo.js'
};
var barFile = {
    source: '(function() {\n\n  console.log(alert(\'alerts suck\'));\n\n}).call(this);\n' + '\n' + barComment
  , sourceFile: 'bar.js'
};

var offset = { line: 2 };
var base64 = combine
  .create('bundle.js')
  .addFile(fooFile, offset)
  .addFile(barFile, { line: offset.line + 8 })
  .base64();

var sm = convert.fromBase64(base64).toObject();
console.log(sm);

{ version: 3,
  file: 'bundle.js',
  sources: [ 'foo.coffee', 'bar.coffee' ],
  names: [],
  mappings: ';;;AAAA;CAAA;CAAA,CAAA,CAAA,IAAO,GAAK;CAAZ;;;;;ACAA;CAAA;CAAA,CAAA,CAAA,IAAO,GAAK;CAAZ',
  sourcesContent:
   [ 'console.log(require \'./bar.js\')\n',
     'console.log(alert \'alerts suck\')\n' ] }

Installation

npm install combine-source-map

API

create()

/**
 * @name create
 * @function
 * @param file {String} optional name of the generated file
 * @param sourceRoot { String} optional sourceRoot of the map to be generated
 * @return {Object} Combiner instance to which source maps can be added and later combined
 */

Combiner.prototype.addFile(opts, offset)

/**
 * Adds map to underlying source map.
 * If source contains a source map comment that has the source of the original file inlined it will offset these
 * mappings and include them.
 * If no source map comment is found or it has no source inlined, mappings for the file will be generated and included
 * 
 * @name addMap
 * @function
 * @param opts {Object} { sourceFile: {String}, source: {String} }
 * @param offset {Object} { line: {Number}, column: {Number} }
 */

Combiner.prototype.base64()

/**
* @name base64
* @function
* @return {String} base64 encoded combined source map
*/

Combiner.prototype.comment()

/**
 * @name comment
 * @function
 * @return {String} base64 encoded sourceMappingUrl comment of the combined source map
 */

removeComments(src)

/**
 * @name removeComments
 * @function
 * @param src 
 * @return {String} src with all sourceMappingUrl comments removed
 */

Example

Read and run the more elaborate example in order to get a better idea how things work.