grunt-pre-concat
Grunt.js task that prepares javascript files for concatenation by setting them in correct order using dependency tree.
Getting Started
This plugin requires Grunt >0.4.4
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-pre-concat --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "preConcat" task
Overview
In your project's Gruntfile, add a section named preConcat
to the data object passed into grunt.initConfig()
.
grunt;
Options
options.cwd
Type: String
Default value: 'src'
Current working directory for the task. During execution task generates names for each file given as source.
That name is concatenation of file path starting from cwd
without file extension.
Example:
For file in src/js/controllers/myController.js
, when cwd
is src/js
, generated file id would be controllers.myController
.
Usage Examples
Assume we have following javascript source files structure:
- src
- controllers
- loginCtrl.js
- mainCtrl.js
- directives
- labelDirective.js
- panelDirective.js
- services
- backendService.js
- loginService.js
- utils
- utils.js
- module.js
- controllers
When we are using just concat task with src
set to src/**/*.js
pattern, content order of output file would be :
- module.js
- loginCtrl.js
- mainCtrl.js
- labelDirective.js
- panelDirective.js
- backendService.js
- loginService.js
- utils.js
If we want to modify order in which task concatenates source files we have to put them in required order in grunt config using full paths, which might be cumbersome as codebase grows.
Here comes preConcat task, which pre-generates automatically config for concat task using dependencies defined in special directives in source code comments.
Defining dependencies
To defined dependencies between files we have to add special comment with @require <dependency_name>
at the files header. Dependency name is created from the file path starting from cwd
with extension cut off. E.g. for panelDirective.js
generated name would be directives.panelDirective
.
Let's say that part of dependency tree in our example is loginCtrl.js -> loginService.js -> module.js
. Then those file headers would have respectively:
loginCtrl.js
// @require services.loginService {...};
loginService.js
// @require module {...};
We can add as many dependencies as we want. For examples if loginService.js
dependes, in addition, on utils.js
we can set file header to:
// @require module// @require uitls.utils {...};
Gruntfile.js
Following code snippet ilustrates sample Gruntfile.js
configuration for example described in previous sections:
module { grunt; grunt; grunt; grunt; };
First of all preConcat task was designed as helper for concat task. So using it without it does not make any sense.
As preConcat generates configuration for concat, we don't have to define it manually but preConcat should be always executed before actual concat.
Possible problems
Cyclic dependencies
This task detects situations when you defined cyclic dependency in your sources. In such cases error with detailed information is thrown.
Wrong dependency name
If you make typo or other mistake when declaring dependency name (e.g. serices.loginService
),
task will fail with appropriate error message.
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.
Release History
2014-04-12 Initial version 1.0.0 released. 2016-02-29 Patch 1.1.0 with added support for GruntJS 1.0