grunt-neuter

grunt-neuter

Concatenate files in the order you require.

Getting Started

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, install this plugin with this command:

npm install grunt-neuter --save-dev

or for the latest version

npm install git://github.com/trek/grunt-neuter.git --save-dev

Then include the tasks in your project's Gruntfile

grunt.loadNpmTasks('grunt-neuter');

Neuter task

Run this task with the grunt neuter command.

This task is a multi task so any targets, files and options should be specified according to the multi task documentation.

Use a neutering task for

1. Breaking up a project into files: some applications are easier to reason about when their source is divided into files and organzied with directories

2. Keep intra-project dependency management inline: rather than have to track and updated files and their order in a Make/Cake/Rakefile or a JSON object.

3. Have files separated in debugging, combined in production: When using good development tools you want to easily map your debugging efforts to a specific file, not read through one giant file.

4. Not need a dependency management library deployed: for applications deployed as a single file the benefits of modular file loaders like require.js is minimized.

Neuter is based on the Rake pipline web-filter of the same name

Example

Given the following files:

a.js

require('b');

var myVariable = 'hello';

b.js

var variableFromB = 'b';
window.availableEverywhere = true;

Resulting output would be

(function(){
  var variableFromB = 'b';
  window.availableEverywhere = true;
})();

(function(){

  var myVariable = 'hello';
})();

Relative Paths

Relative paths using a dot to indicate the file's current directory are valid as well:

a.js

require('dir/b');

var variableFromA = 'a';

dir/b.js

require('./c');

var variableFromB = 'b';

dir/c.js

var variableFromC = 'c';

Outputs

(function(){
  var variableFromC = 'c';
})();

(function(){

  var variableFromB = 'b';
})();

(function(){

  var variableFromA = 'a';
})();

Note that directory traversal using ../ is not supported.

Example Gruntfile Use

grunt.initConfig({
  neuter: {
    application: {
      src: 'tmp/application.js',
      dest: 'app/index.js'
    }
  }
});

or

grunt.initConfig({
  neuter: {
      'tmp/application.js' :'app/index.js'
  }
});

Options

template

Type: String

Default: "(function){ {%= src %} })();"

The wrapper around your code. Defaults to a closure-style function so locally declared variables won't leak into the global scope. The text of your source JavaScript file is available as src within a template.

basePath

Type: String

Default: ""

Specifying a base path allows you to omit said portion of the filepath from your require statements. For example: when using basePath: "lib/js/" in your task options, require("lib/js/file.js"); can instead be written as require("file.js");. Note that the trailing slash must be included.

filepathTransform

Type: Function

Default: function(filepath){ return filepath; }

Specifying a filepath transform allows you to control the path to the file that actually gets concatenated. For example, when using filepathTransform: function(filepath){ return 'lib/js/' + filepath; } in your task options, require("lib/js/file.js"); can instead be written as require("file.js"); (This achieves the same result as specifying basePath: "lib/js/"). When used in conjunction with the basePath option, the base path will be prepended to the filepath argument and a second argument will be provided that is the directory of the file without the basePath.

includeSourceURL

Type: Boolean

Default: false

Includes the path to your source JavaScript file as //@ sourceURL="path/to/my/file.js" for nicer debugging. Note that this wraps your source JavaScript file (as a string) with eval and should not be used in prouduction.

separator

Type: String

Default: "\n"

Neutered files will be joined on this string. If you're post-processing concatenated JavaScript files with a minifier, you may need to use a semicolon ';' as the separator although the semicolon at the end of the template should suffice.

skipFiles

Type: Array

Default: []

A list of files being required that should not be checked for further require statements. Useful for libraries that support other module building methods and leave their requires around in a way that isn't meaningful to neutering.

process

Type: Boolean Object Function Default: false

Process source files before concatenating, either as templates or with a custom function (similar to grunt-contrib-concat). When using grunt for templating, the delimiters default to neuter's own special type ({% %}), which helps avoid errors when requiring libraries like Underscore or Lo-Dash.

• false - No processing will occur.
• true - Process source files using grunt.template.process without any data.
• options object - Process source files using grunt.template.process, using the specified options.
• function(src, filepath) - Process source files using the given function, called once for each file. The returned value will be used as source code.

(Default processing options are explained in the grunt.template.process documentation)