Noticeably Playful Monkeys

    grunt-feature

    0.3.0 • Public • Published

    grunt-feature build status

    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.loadNpmTasks('grunt-feature');

    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.initConfig({
     
      feature: {
     
        options: {
     
          // global options
     
          toggles: {
           // some global toggles
          }
     
        },
     
        your_target: {
     
         options: {
     
         // task options,
     
         toggles: {
     
         // some target toggles
     
         }
     
         },
     
            files: {
                'some/path/to/_config.scss': ['framework/config.json', 'site/config.json']
                'some/path/to/config.json': ['framework/config.json', 'site/config.json']
            }
     
        }
     
      }
     
    })

    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

    Keywords

    none

    Install

    npm i grunt-feature

    DownloadsWeekly Downloads

    0

    Version

    0.3.0

    License

    none

    Last publish

    Collaborators

    • indieisaconcept