grunt-concat-sourcemap

Concatenate files and generate a source map file.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-concat-sourcemap --save-dev

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-concat-sourcemap');

The "concat_sourcemap" task

Overview

In your project's Gruntfile, add a section named concat_sourcemap to the data object passed into grunt.initConfig().

grunt.initConfig({
  concat_sourcemap: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    }
  }
})

Options

options.separator

Type: String Default value: grunt.util.linefeed

The value that will be used to separate lines when generating sourceMappings.

options.sourceRoot

Type: String Default value: ''

An optional root for all relative URLs in the source map.

options.sourcesContent

Type: Boolean Default value: false

An optional flag that tells the source map generator whether or not to include all original sources in the map. sourcesContent is an array of contents of the original source files. This is useful if you don't want to have to upload original src files to the webserver that will be serving the sourcemap.

options.process

Type: Function Default value: undefined

• undefined - Do not apply any processing to the source files
• function(src, filepath) - Process source files using the given function, called once for each file. The returned value will be used as source code.

Usage Examples

Default Options

In this example, it will concatenate the two specified source files(in order), joining files with default separator(grunt.util.linefeed) and writing the output to dest/default_options.js and dest/default_options.js.map.

grunt.initConfig({
  concat_sourcemap: {
    options: {},
    target: {
      files: {
        'dest/default_options.js': ['src/a.js', 'src/b.js']
      }
    }
  }
})

Using sourcesContent: true

When using sourcesContent: true the resulting sourceMap will include all the contents of each source file inside of an array called sourcesContent

Given sample files as follows:

src/a.js

"file a - line 1";
"file a - line 2";

src/b.js with contents as follows:

"file b - line 1";

and the following Grunt configuration target for concat_sourcemap

grunt.initConfig({
  concat_sourcemap: {
    options: {
      sourcesContent: true
    },
    target: {
      files: {
        'dest/default_options.js': ['src/a.js', 'src/b.js']
      }
    }
  }
})

You would see a resulting dest/default_options.js.map that included sourcesContent like so:

  {
    "version": 3,
    "file": "default_options.js.map",
    "sources": [
      "src/a.js",
      "src/b.js"
    ],
    "names": [],
    "mappings": "AAAA;AACA;AACA;A;ACFA;AACA;A;ACDA;A",
    "sourcesContent": [
      "\"file a - line 1\";\n\"file a - line 2\";\n",
      "\"file b - line 1\";\n"
    ]
  }

Using process

grunt.initConfig({
  concat_sourcemap: {
    options: {
      process: function(src, filepath) {
        return '(function(){' + src + '})();';
      }
    },
    target: {
      files: {
        'dest/closureWrapped.js': ['src/a.js', 'src/b.js']
      }
    }
  }
})

Merging source map files

If input file has source map linkage(e.g. //# sourceMappingURL=.*), grunt-concat-sourcemap will read the source map and merge it into the new one. No option is needed.

The setting is to consume 2 input files generated by grunt-contrib-coffee with sourceMap: true option.

grunt.initConfig({
  coffee: {
    options: { sourceMap: true },
    target: {
      files: {
        'src/file1.js': ['src/file1.coffee'],
        'src/file2.js': ['src/file2.coffee'],
      }
    }
  },
  concat_sourcemap: {
    target: {
      files: {
        'dest/concatenated.js': ['src/*.js']
      }
    }
  }
})

The source map generated by grunt-concat-sourcemap is as below. It refers to original coffee script source files.

{
  "version": 3,
  "file": "concatenated.js",
  "sources": [
    "src/file1.coffee",
    "src/file2.coffee"
  ],
  "names": [],
  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;A;ACAA;AAAA;AAAA;AAAA;AAAA;AAAA;A"
}

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.