AndrewDryga / grunt-bower-installer

Grunt plugin for Bower

grunt-bower-installer

Install Bower packages. Smartly.

Getting Started

If you haven't used grunt before, be sure to check out the Getting Started guide.

Please note, this plugin works only with grunt 0.4+. If you are using grunt 0.3.x then consider an upgrade to 0.4.

From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:

npm install grunt-bower-installer --save-dev

Once that's done, add this line to your project's Gruntfile:

grunt.loadNpmTasks('grunt-bower-installer');

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.

Grunt task for Bower

Overview

In your project's Gruntfile, add a section named bower to the data object passed into grunt.initConfig().

grunt.initConfig({
  bower: {
    install: {
       //just run 'grunt bower:install' and you'll see files from your Bower packages in lib directory
    }
  }
});

Options

options.targetDir

Type: String Default value: ./lib

A directory where you want to keep your Bower packages.

options.overrideBowerDirectory

Type: Boolean Default value: false

Override the bower directory configuration with the targetDir

options.install

Type: Boolean Default value: true

Whether you want to run bower install task itself (e.g. you might not want to do this each time on CI server).

options.cleanTargetDir

Type: Boolean Default value: false

Will clean target dir before running install.

options.cleanBowerDir

Type: Boolean Default value: false

Will remove bower's dir after copying all needed files into target dir.

options.filter

Type: regexp or function Default value: null

A filter to match files against when copying. Returning true or matching doesn't copy the file.

options.copy

Type: Boolean Default value: true

Copy Bower packages to target directory.

options.cleanup

Type: boolean Default value: undefined

NOTE: If set to true or false then both cleanBowerDir & cleanTargetDir are set to the value of cleanup.

options.layout

Type: string or function Default value: byType

There are two built-in named layouts: byType and byComponent.

byType layout will produce the following structure:

lib
|-- js
|   |- bootstrap
|   \- require
|-- css
    \- bootstrap

where js, css come from exportsOverride section described below.

byComponent will group assets by type under component name:

lib
|-- bootstrap
|   |- js
|   \- css
|-- require
    \- js

If you need to support custom layout then you can specify layout as a function of type and component:

var path = require('path');

grunt.initConfig({
  bower: {
    install: {
      options: {
        layout: function(type, component) {
          var renamedType = type;
          if (type == 'js') renamedType = 'javascripts';
          else if (type == 'css') renamedType = 'stylesheets';

          return path.join(component, renamedType);
        }
      }
    }
  }
});

options.verbose

Type: boolean Default value: false

The task will provide more (debug) output when this option is set to true. You can also use --verbose when running task for same effect.

options.bowerOptions

Type: Object Default value: {}

An options object passed through to the bower.install api, possible options are as follows:

{
    forceLatest: true|false,    // Force latest version on conflict
    production: true|false,     // Do not install project devDependencies
}

Usage Examples

Default Options

Default options are good enough if you want to install Bower packages and keep only "main" files (as specified by package's bower.json) in separate directory.

grunt.initConfig({
  bower: {
    install: {
      options: {
        targetDir: './lib',
        layout: 'byType',
        install: true,
        verbose: false,
        cleanTargetDir: false,
        cleanBowerDir: false,
        bowerOptions: {}
      }
    }
  }
});

Custom Options

In this initial version there are no more options in plugin itself. BUT!

Advanced usage

At this point of time "Bower package" = "its git repository". It means that package includes tests, licenses, etc. Bower's community actively discusses this issue (GitHub issues #46,#88, on Google Groups) That's why you can find such tools like blittle/bower-installer which inspired this project.

Okay, if you want more than "main" files in ./lib directory then put "exportsOverride" section into your bower.json:

{
  "name": "simple-bower",
  "version": "0.0.0",
  "dependencies": {
    "jquery": "~1.8.3",
    "bootstrap-sass": "*",
    "requirejs": "*"
  },
  "exportsOverride": {
    "bootstrap-sass": {
      "js": "js/*.js",
      "scss": "lib/*.scss",
      "img": "img/*.png"
    },
    "requirejs": {
      "js": "require.js"
    }
  }
}

grunt-bower-installer will do the rest:

• If Bower package has defined "main" files then they will be copied to ./lib/<package>/.
• If "main" files are empty then the whole package directory will be copied to ./lib.
• When you define "exportsOverride" only asset types and files specified by you will be copied to ./lib.

For the example above you'll get the following files in .lib directory:

jquery/jquery.js
js/bootstrap-sass/bootstrap-affix.js
...
js/bootstrap-sass/bootstrap-typeahead.js
js/requirejs/require.js
scss/bootstrap-sass/_accordion.scss
...
scss/bootstrap-sass/_wells.scss
scss/bootstrap-sass/bootstrap.scss
scss/bootstrap-sass/responsive.scss
img/bootstrap-sass/glyphicons-halflings-white.png
img/bootstrap-sass/glyphicons-halflings.png

Wildcard and RegExp support

If you have the same override rules for multiple Bower components you can make use of simple wildcard:

{
    "exportsOverride": {
        "bootstrap-*": {        // will match 'bootstrap-modal', 'bootstrap-notify', etc.
          "js": "**/*.js",
          "css": "**/*.css"
        },

        "*": {                  // will match everything else
          "js": "**/*.js",
          "css": "**/*.css"
        }
    }
}

You can use syntax which mirrors native JavaScript RegExp literal syntax, e.g. /bootstrap.+/ or even /jquery.date.v(\\d{1}).\\w{1}/, if you have complex matching rules.

Usage example in bower.json:

{
  "exportsOverride": {
    "/jquery.date.v(\\d{1}).\\w{1}/": { // will match 'jquery.date.v1.2', 'jquery_date_v1_2'
      "js": "js/*.js"
    }
  }
}

Caveats

• An evaluation order depends on the order of entries in exportsOverride section in your bower.json.
• Pay attention to what characters you use in RegExp overrides - '.' and '*' has special meaning in regular expressions.
• If you put * as the first entry in exportsOverride, it'll match everything, so other rules will be skipped.

Contributing

Please, use devel branch for all pull requests.

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

• 2013/11/10 - v0.3.4 - Fix paths handling of glob patterns in components' "main" files.
• 2013/11/08 - v0.3.3 - Added bowerOptions (thanks to @xzyfer), fixed paths handling using glob module (thanks to @leon).
• 2013/09/08 - v0.3.2 - Update to Bower 1.2.x, fixed logging issue.
• 2013/08/09 - v0.3.1 - Update to Bower 1.1.x, fixed compatibility issue with new Bower's API.
• 2013/08/05 - v0.3.0 - Update to Bower 1.0.x, added wildcard/regex support, improve docs.
• 2013/05/11 - v0.2.3 - Update to bower 0.9.x, docs improvement, Windows-compatible paths in tests.
• 2013/04/23 - v0.2.2 - Fix backward-compatibility issue (related to cleanup option).
• 2013/04/22 - v0.2.1 - Split 'install' to 'install' and 'copy' steps to support flexible workflow, add support for grunt's --base option.
• 2013/03/30 - v0.2.0 - Added support for flexible assets layout, honor native Bower's configuration, reduce log output.
• 2013/03/18 - v0.1.1 - Updated dependencies, minor fixes.
• 2012/11/25 - v0.1.0 - Initial release.

License

Copyright (c) 2012-2013 Ivan Yatskevich

Licensed under the MIT license.

https://github.com/yatskevich/grunt-bower-installer/blob/master/LICENSE-MIT