Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/timmywil/grunt-bowercopy

Scrupulously manage file locations for bower dependencies.
https://github.com/timmywil/grunt-bowercopy

Last synced: 2 days ago
JSON representation

Scrupulously manage file locations for bower dependencies.

Awesome Lists containing this project

README

        

# grunt-bowercopy
[![Build Status](https://travis-ci.org/timmywil/grunt-bowercopy.png?branch=master)](https://travis-ci.org/timmywil/grunt-bowercopy) [![Greenkeeper badge](https://badges.greenkeeper.io/timmywil/grunt-bowercopy.svg)](https://greenkeeper.io/)

> Wrangle those bower dependencies and place each one where it's supposed to be.

- Automatically position your dependencies where you want them in your repository.
- [Track your dependencies](http://addyosmani.com/blog/checking-in-front-end-dependencies/) without committing the entire Bower components folder.
- Reduce build times by compiling only what you need from the `bower_components` directory.

## Workflow

Whenever you add a new bower dependency, add which file should be copied and where to your Gruntfile `"bowercopy"` config. Then, run `grunt bowercopy`.

By default, bowercopy runs `bower install` for you (turn this off with the `runbower` option). Your bower directory is not removed so you can see which files you need from each component.
It is suggested that you add the bower directory (usually `'bower_components'`) to your `.gitignore`.

## Getting Started
This plugin requires Grunt.

If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```shell
npm install grunt-bowercopy --save-dev
```

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

```js
grunt.loadNpmTasks('grunt-bowercopy');
```

*Note: have a look at [load-grunt-tasks](https://github.com/sindresorhus/load-grunt-tasks) so you can skip this step for all your grunt plugins.*

## The "bowercopy" task

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

```js
grunt.initConfig({
bowercopy: {
options: {
// Task-specific options go here
},
your_target: {
// Target-specific file lists and/or options go here
}
}
});
```

### Options

#### options.srcPrefix
Type: `String`
Default value: The `directory` property value in your `.bowerrc` or `'bower_components'` if the `.bowerrc` cannot be found.

`srcPrefix` will prefix your source locations with the correct bower folder location.

#### options.destPrefix
Type: `String`
Default value: `''`

`destPrefix` will be used as the prefix for destinations.

#### options.runBower
Type: `Boolean`
Default value: `true`

Run `bower install` in conjunction with the `bowercopy` task.

#### options.report
Type: `Boolean`
Default value: `true`

Report any modules in your bower.json that have not been configured to copy at least one file with `bowercopy`.

**Note:** *The clean option reports the same thing, so this option is ignored if clean is true.*

#### options.clean
Type: `Boolean`
Default value: `false`

Removes the bower components directory on completion. The folder path that is removed is `options.srcPrefix`.

**Note: the directory will only be removed if the following conditions are met.**

1. All task targets are run (i.e. grunt-bowercopy was run with the command `grunt bowercopy` and not `grunt bowercopy:target`).
2. At least one thing was copied from each bower component (grunt-bowercopy tracks this for you).

#### options.ignore
Type: `Array`
Default value: `[]`

Using the `report` or `clean` option, `grunt-bowercopy` tracks which dependencies have at least one file copied.
The `ignore` option can be used to specify any bower dependencies that aren't copied, but need to be defined in your `bower.json` anyway.

#### options.copyOptions
Type: `Object`
Default value: `{}`

Options to pass to `grunt.file.copy` when copying the files. See [grunt.file.copy](http://gruntjs.com/api/grunt.file#grunt.file.copy)

### Usage Examples

```js
grunt.initConfig({
bowercopy: {
options: {
// Bower components folder will be removed afterwards
clean: true
},
// Anything can be copied
test: {
options: {
destPrefix: 'test/js'
},
files: {
// Keys are destinations (prefixed with `options.destPrefix`)
// Values are sources (prefixed with `options.srcPrefix`); One source per destination
// e.g. 'bower_components/chai/lib/chai.js' will be copied to 'test/js/libs/chai.js'
'libs/chai.js': 'chai/lib/chai.js',
'mocha/mocha.js': 'libs/mocha/mocha.js',
'mocha/mocha.css': 'libs/mocha/mocha.css'
}
},
// Javascript
libs: {
options: {
destPrefix: 'public/js/libs'
},
files: {
'jquery.js': 'jquery/jquery.js',
'require.js': 'requirejs/require.js'
},
},
plugins: {
options: {
destPrefix: 'public/js/plugins'
},
files: {
// Make dependencies follow your naming conventions
'jquery.chosen.js': 'chosen/public/chosen.js'
}
},
// Less
less: {
options: {
destPrefix: 'less'
},
files: {
// If either the src or the dest is not present,
// the specified location will be used for both.
// In other words, this will copy
// 'bower_components/bootstrap/less/dropdowns.less' to 'less/bootstrap/less/dropdowns.less'
// See http://gruntjs.com/configuring-tasks#files for recommended files formats
src: 'bootstrap/less/dropdowns.less'
}
},
// Images
images: {
options: {
destPrefix: 'public/images'
},
files: {
'account/chosen-sprite.png': 'chosen/public/chosen-sprite.png',
'account/[email protected]': 'chosen/public/[email protected]'
}
},
// Entire folders
folders: {
files: {
// Note: when copying folders, the destination (key) will be used as the location for the folder
'public/js/libs/lodash': 'lodash',
// The destination can also be a folder
// Note: if the basename of the location does not have a period('.'),
// it is assumed that you'd like a folder to be created if none exists
// and the source filename will be used
'public/js/libs': 'lodash/dist/lodash.js'
}
},
// Glob patterns
glob: {
files: {
// When using glob patterns, destinations are *always* folder names
// into which matching files will be copied
// Also note that subdirectories are **not** maintained
// if a destination is specified
// For example, one of the files copied here is
// 'lodash/dist/lodash.js' -> 'public/js/libs/lodash/lodash.js'
'public/js/libs/lodash': 'lodash/dist/*.js'
}
},
// Glob without destination
globSrc: {
options: {
destPrefix: 'public/js/libs'
},
// By not specifying a destination, you are denoting
// that the lodash directory structure should be maintained
// when copying.
// For example, one of the files copied here is
// 'lodash/dist/lodash.js' -> 'public/js/libs/lodash/dist/lodash.js'
src: 'lodash/**/*.js'
},
// Main pragma
// Adding :main to the end of a source path will retrieve the main file(s) for that package
// If the main property is not specified by a package, bowercopy will fail
main: {
src: 'jquery.minlight:main',
dest: 'public/js/plugins/'
}
}
});
```

## Contributing
Follow the same coding style present in the repo and add tests for any bug fix or feature addition.

See the [CONTRIBUTING.md](https://github.com/timmywil/grunt-bowercopy/blob/master/CONTRIBUTING.md) for more info.

## Release History

- **1.1.0** (*6-23-2014*) Add :main pragma and `ignore` option.
- **1.0.1** (*6-12-2014*) Updated node modules
- **1.0.0** (*3-26-2014*) Version 1
- **0.9.0** (*3-3-2014*) Warn if a source location was not found.
- **0.8.0** (*2-21-2014*) Adds support for folders for destinations when copying individual files.
- **0.7.1** (*1-20-2014*) Fix Windows issue with path seperators.
- **0.7.0** (*1-13-2014*) Add `options.report`. Camelcase `options.runBower`. Fix an issue with a source format (gh-9).
- **0.6.0** (*1-13-2014*) Add glob matcher.
- **0.5.0** (*12-31-2013*) Add `options.copyOptions` to be passed along to `grunt.file.copy` and fix issue with local-only bower usage.
- **0.4.0** (*12-3-2013*) Update grunt to 0.4.2. Add the ability to copy folders.
- **0.3.0** (*12-2-2013*) Add clean option for removing the bower components directory on full task completion.
- **0.2.0** (*11-19-2013*) Report any bower components not configured to be copied when all targets are run together.
- **0.1.0** (*11-19-2013*) First Release

## License
Copyright (c) 2014 Timmy Willison. Licensed under the MIT license.