grunt-feature
A grunt task which can be used to generate feature configuration files to support code being released early and often and to synchronise features between JavaScript & CSS.
Getting Started
If you haven't used grunt before, be sure to check out the Getting Started guide.
From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:
npm install grunt-feature --save-dev
Once that's done, add this line to your project's Gruntfile:
grunt;
If the plugin has been installed correctly, running grunt --help
at the command line should list the newly-installed plugin's task or tasks. In addition, the plugin should be listed in package.json as a devDependency
, which ensures that it will be installed whenever the npm install
command is run.
The "feature" task
grunt-feature
will generate a configuration file which can be consumed by other tasks.
For example if you are using require.js with pragmas or similar, the task can be used to control which features are to be included as part of an r.js optimizer build.
Equally a configuration file can be generated to introduce feature toggling as part of a CSS pre-processor build.
The real power is when you combine the two. If you no-longer need a feature, or a feature is to be only used by a subset of sites the task can be used to omit both the JavaScript and CSS for a given feature.
Defining a feature
Features are managed via json
configuration files which are used to describe what a feature does and more importantly whether it should be enabled.
If multiple configuration files are passed, these are deeply merged together with the resulting conguration file a combination of all options, either added or overriden.
When managing multiple web-sites which share a common code base and build process, this provides scope to turn off common features and manage those which are localised.
When defining features the resulting generated file will be namespaced based upon the source json object processed.
feature.json
"feature-1": true "feature-2": false "feature-3": "description": "Vehicula Euismod Cras Ornare Fringilla" "value": true "feature-4": "a": true "b": false "c": "description": "Vehicula Euismod Cras Ornare Fringilla" "value": true "children": "a": false
Defining a feature in feature.json
_feature.scss
$feature-1: true !default
$feature-2: false !default
$feature-3: true !default // Vehicula Euismod Cras Ornare Fringilla
$feature-4-a: true !default
$feature-4-b: false !default
$feature-4-c: true !default // Vehicula Euismod Cras Ornare Fringilla
$feature-4-c-d: false !default
Namespaces
A base namespace can be defined for a merged config is flattened. This can be specified by passing global or target specific options.
options: namespace: 'ft' delimiter: '_'
The configuration above would generate named features with ft
as a suffix using _
as a delimiter.
Templates
Templates can be used to control the output for a configuration file.
ERB style underscore templates are used by default via grunt.template.process
however an alternative template engine can be selected by passing through a function via options.engine
.
Note as of release 0.3.0 Handlebar support is no-longer provided by default (see below)
options.engine
To override the default template engine should you wish to use something other than underscore templates this is possible using options.engine
.
options: {
engine: function (/* String */ template, /* Object */ data) {
var compiled = require('Handlebars').compile(template);
return compiled(data);
}
}
options.engine example
Specifying a template
The default template to use will be automatically determined based upon the destination file extension unless an override is explicitly provided as an option in the destinaton filename. In addition to this a custom named template path can also be specified should the need arise to define one.
When specifying a template the destination extension is used for the generated file, however this can be overriden using the following.
Filename
{name}.{extension}.{erb,hbs} =>
mytemplate.scss.hbs`
Grunt Config
file: 'some/path/to/config.{json,scss,less,commonjs}': 'framework/config.json' 'site/config.json'
When you have templates which may generate the same file type and you want to use the above format use a grunt
template to add the template name to the template if needed.
Note grunt by default will will subsitute this template during processing. To defer this so that grunt-feature
can pass values use the following format. Note the use of !
this prevents grunt from processing the template.
<%=! template %>
grunt-feature
comes bundled with templates for JavaScript ( AMD & CommonJS ), JSON and SCSS/Less/Stylus/Html by default.
your_target: options: template: custom: 'templates/custom.hbs' toggles: two: true files: 'tmp/_config.scss': '<%=fixtures.path %>' // use scss template 'tmp/_config.less': '<%=fixtures.path %>' // use less template 'tmp/config.json': '<%=fixtures.path %>' // use json template 'tmp/config-amd.amd.js': '<%=fixtures.path %>' // use amd template 'tmp/config-commonjs.commonjs.js': '<%=fixtures.path %>' // use commonjs template 'tmp/config-custom.custom.js': '<%=fixtures.path %>' // use custom template found in options.template.custom 'tmp/config-glob-{%= template %}.{scss,less,json,amd,commonjs}': '<%=fixtures.path %> // Rolls up the above into a single configuration'
Specifying templates
Within a template the following data can be acessed.
Data | Description |
---|---|
src | Deeply merged config object |
namespace | Flattened namspaced version of config |
options | Task options |
Overview
In your project's Gruntfile, add a section named feature
to the data object passed into
grunt.initConfig()
.
grunt
Release History
- 26/10/2013 0.3.0
- Handlebar templates deprecated, ERB now default via grunt
options.engine
support added to allow alternative template engines such as handlebars- html template support added for generating config listing.
- 26/10/2013 0.2.0 | Added basic glob-like support for file dest and tweaked templates
- 21/10/2013 0.1.1 | Fixed namespace support
- 21/10/2013 0.1.0 | Intial release