grunt-useuses
A grunt plugin allowing you to use @uses
annotations to load dependencies for your javascript files.
This plugin resolves dependencies recursively, and builds a list of correctly sorted, non-duplicate dependencies.
Note: This plugin doesn't support external urls yet. If you need support for this, create an issue here, or submit a pull request.
Getting Started
This plugin requires Grunt ~0.4.2
or older.
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-useuses --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "useuses" task
Overview
In your project's Gruntfile, add a section for this task to the data object passed into grunt.initConfig()
.
Example:
grunt;
Options
aliases
Allows you to specify aliases for your dependencies.
Example:
grunt;
Allows you to do the following in your javascript files:
/** * Some cool file. * * Gives you back assets/vendor/angular/angular.min.js * @uses angular.min * * Gives you back assets/vendor/angular/angular.js * @uses angular */
searchPaths
Allows you to specify searchPaths for useuses. It's exactly what it sounds like, in that it will apply its search algorhythm in the supplied searchPaths as well.
Example:
grunt;
Allows you to do the following in your javascript files:
/** * Some cool file. * * Gives you back assets/bower_components/angular/angular.min.js * @uses angular/angular.min */
Syntax
The syntax is pretty straight forward. Usually your javascript files will already have a docblock at the beginning of the file:
/* * My file * * Some info about My file * * @author RWOverdijk * @version 0.1.0 * @license MIT */
This plugin allows you to add a new annotation by the name of @uses
in the following ways:
/* * Relative to your current dir: * @uses ./my-dependency.js * * Without the .js extension (will load ./my-dependency.js): * @uses ./my-dependency * * A package with an index.js (will load ./package/index.js) * @uses ./package * * Paths relative to your project directory: * @uses assets/scripts/common/filter/age.js */
The advantages are clear.
You can specify dependencies in annotations making development easier, as you have a reference to the file's dependencies. The files individually still work without any dependencies, and you can still build a concatenated file.
Examples
I've made a very small, but very informative example. You can find it in the example
directory.