bower-files
v4.0.4
Published
Pulls in dynamic list of filepaths to bower components
Downloads
1,457
Readme
bower-files
Looking for another maintainer. I have been cleaning up my packages and no
longer have the energy to maintain this package. If you are interested in
taking over, please reach out. Otherwise, eventually I will have this package
removed. There are much better alternatives that have much better community
adoption/support. The best alternative I could find was
wiredep. Honestly, I don't use bower
anymore, and it's been a long time since I have. I've opted to use webpack with
standard npm
installs. If you haven't tried that yet, you should definitely
give it a try.
Help you dynamically include your bower components into your build process.
The Problem
Bower is a great tool to bring in your front-end dependencies (and their dependencies) to your project. But if you want them to be included in your build process, you need to manually enter them in to your build process. If you add or remove dependencies, you need to modify your build process configuration files.
The Solution
bower-files
aims to simplify your build process setup by dynamically getting
the library files for you to include in whatever build process you use. It
splits up the files by extension, and puts them in the order they need to be in,
in order to work correctly in the browser.
4.x
Just updated dependencies and support for only node >= 4.x. Also added deprecation notice. Otherwise, api is exactly the same and should work the same as it did before.
3.x
There are breaking changes in 3.x. A few features were requested, but with the way that the code was organized, it was going to be pretty difficult and it would make the codebase even more complicated. In the end, I refactored most every piece to follow a more modular approach. I am much happier with the code base than I was, but it's not perfect. I'm going to be slowly refactoring litte pieces here and there, but the api should not change much from here.
For those of you who want the old 2.x api, just use it the same way, but adding
a .old
before the function call.
var lib = require('bower-files').old(options);
With that you get the benefit of using the new modular code, and it still passes all of the old tests (which had 100% api and code coverage). 2.x Docs
Installation
npm install bower-files --save-dev
Usage
gulp example...
var gulp = require('gulp');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var lib = require('bower-files')();
gulp.task('default', function () {
gulp.src(lib.ext('js').files)
.pipe(concat('lib.min.js'))
.pipe(uglify())
.pipe(gulp.dest('public/js'));
});
or a grunt example...
var lib = require('bower-files')();
module.exports = function (grunt) {
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
uglify: {
dist: {
files: {
'build/lib.min.js': lib.ext('js').files
}
}
},
cssmin: {
dist: {
files: {
'build/lib.min.css': lib.ext('css').files
}
}
}
});
grunt.loadNpmTasks('grunt-contrib-uglify');
grunt.loadNpmTasks('grunt-contrib-cssmin');
grunt.registerTask('default', ['uglify', 'cssmin']);
};
or via the CLI (node-modules/.bin
needs to be in your PATH
):
$ bower-files js css
Other Solutions
There are other modules that do this same thing, but in different ways:
Options
The following gives you an instance of your bower files.
var lib = require('bower-files')(/* options */);
Those options are as follows:
options.cwd
{String}
Default: process.cwd()
Your current working directory where your bower.json
lives. This is also where
it will start looking at .bowerrc
. MUST be an absolute path.
options.json
{String}
Default: 'bower.json'
The relative path to your bower.json
. This is relative to your options.cwd
.
options.componentJson
{String}
Default: '.bower.json'
When you run bower install jquery
it installs the jquery
component into a
folder bower_components/jquery/
. In that directory, there is a .bower.json
file put there by bower, which essentially is a copy of the other bower.json
,
but it's what is officially used by bower. If for some reason you are using a
different package manager that uses a different file, then you can change it
with this option. Otherwise, leave it as is.
options.overrides
{Object}
Default: {}
An overrides object to override specific package main files. Occasionally,
you'll find a bower component that has no defined main
property. So here, you
pass in an object that looks like this:
var lib = require('bower-files')({
overrides: {
jQuery: {
main: './dist/jquery.min.js',
dependencies: {}
}
}
});
Note that you can also add this POJO into bower.json
in JSON
form, but if
you specify an overrides directly when calling bower-files
, it will override
the bower.json
version.
options.dir
{String}
Default: 'bower_components'
The directory that your bower_components directory is set. Note that this module
will automatically read your .bowerrc
file, so if you already have it being
set there, you don't need to set this option. It also follows the same
.bowerrc
rules that bower
follows
options.camelCase
{Boolean}
Default: true
When you get a dependency hash using the .deps
, by default, it will return
the components in camelCase. So if you have angular-route
as a dependency,
it will be returned in the dependency hash as angularRoute
. To prevent this
from happening, pass false to this option. Example:
var lib = require('bower-files')({camelCase: false}).deps;
lib['angular-route']; // instead of lib.angularRoute
API
Getting the files and filtering through them can be a pain without this module. This API is designed to be easy to understand. If you don't like it, PRs are welcome.
First, you need your BowerFiles instance:
var lib = require('bower-files')();
At this point, bower-files
has gotten a list of all the components and their
dependencies. Now it's up to you to use the API to filter those files.
Chainable Methods
The following methods are chainable. At the end, you will need to get the
files
property to get the array of files.
lib.files; // returns all of the files
You may also get the deps
property, which will be an object hash with all of
the bower components as keys. Note that this is not guaranteed to be in the
correct order. If you need the correct order, use the next option.
lib.deps;
/*
{
jquery: [...],
bootstrap: [...]
}
*/
You can also get an array of all of the dependencies with their names and files.
lib.depsArray
/*
[
{
name: 'jquery',
files: [...]
},
{
name: 'bootstrap',
files: [...]
}
]
*/
lib.self()
By default the array of files you get only contain your dependencies defined in
the dependencies
property in your bower.json
. This allows you to also get
the files defined in the main
property in your bower.json
.
lib.self().files;
lib.self().deps;
lib.relative('/')
Default: process.cwd()
Converts the file paths to be relative to the provided path, defaults to process.cwd()
lib.relative(__dirname).files;
lib.main(false)
Default: true
This gives you the ability to remove main dependencies from the file list.
lib.dev().main(false).files;
lib.dev().main(false).deps;
lib.fileListProps(props, useOne)
Default: ['main'], true
This lets you select which bower properties are used when generating a file list
for a component. For example, it seems that the bower standard for lists of
files used by tools like this one is to use the files
property. You could use
lib.fileListProps('files')
to utilize that property instead of the other one.
You could also select both: lib.fileListProps(['files', 'main'])
and it would
remove the duplicate files that match both the main property definition and the
files property definition (it expands globs and uniquifies the lists)
The second option allows you to specify whether or not you want it to stop
trying to read additional file list properties when it finds one. For example,
you may specify ['files', 'main']
, and then true
as the second option, and
all components with a files
property would ignore the 'main' property.
If it's set to false, it would include all of the files in the 'main' property.
lib.fileListProps('files').files;
lib.fileListProps(['files', 'main']).files;
lib.ignoreListProps(props)
Default []
This lets you select which bower properties are used when ignore globs of files. This is to support the bower spec which allows you to use globs in the "files" property, and "ignore" which would ignore groups of files that match the "files" patterns.
lib
.fileListProps('files')
.ignoreListProps('ignore')
.files;
lib.dev()
This throws in your devDependencies
. By default, they come before the normal
dependencies, but you can put them after by calling lib.dev('after')
lib.dev().files;
lib.dev().deps;
lib.ext('js')
Gives you the files with the given extension(s). Accepts a string, array of
strings, or a boolean. The strings are extensions that you would like to filter
by (without the '.'). If you pass true
, it will return an object whose
properties are all of the extensions.
lib.ext('js').files; // Gets all .js files
lib.ext(['css', 'less']).files; // Gets all .css and .less files
lib.ext('css').ext('less').files; // Same as above
lib.ext(true).files; // Get an object like:
/*
{
js: ['what.js', 'who.js'],
css: ['when.css'],
less: ['why.less']
}
*/
lib.ext('js').deps;
/*
{
jquery: ['/path/to/jquery.js'],
bootstrap: ['/path/to/bootstrap.js']
}
*/
lib.ext(true).deps;
/*
{
jquery: { js: ['/path/to/jquery.js'] },
bootstrap: {
js: ['/path/to/bootstrap.js'],
css: ['/path/to/bootstrap.css'],
less: ['/path/to/bootstrap.less'],
you get the picture...
}
}
*/
lib.match('!**/*.min.js')
Allows you to glob match the files. Accepts a string, or array of strings. The files have to match all of the given glob strings to make it through.
The matches are done relative to process.cwd(). So if you wanted to get all of
the bootstrap files by matching, you would use '*/bootstrap/**'
as a pattern.
// Gets all .js files that aren't .min.js files
lib.match('**/*.js').match('!**/*.min.js').files;
lib.join({font: ['eot', 'woff', 'ttf', 'svg']})
Allows you to join files of a certain extension into another extension. Accepts
an object as formed above and in the example below. It's only really useful if
you plan on using .ext(true)
to split by extension, otherwise you can just use
lib.ext(['eot', 'woff', 'ttf', 'svg']).files
to get the files you need.
// Gets all the font files, from bootstrap for example
lib.join({font: ['eot', 'woff', 'ttf', 'svg']}).files
Non-Chainable
There's really only one method, and it could be made chainable really easy, but this method is really a catch all of all of the above methods.
lib.filter({/* options */})
The object given have all of the above options given through the chainable methods. Below is a full example.
lib.filter({
self: true,
dev: true,
ext: 'js',
match: ['!**/*.min.js'],
join: {
js: ['js', 'jsx']
}
});
// chainable alternative
lib.self()
.dev()
.ext('js')
.match('!**/*.min.js')
.join({js: ['js', 'jsx']})
.files;
The above returns all of the .js
files, including the ones in your
bower.json
, and the devDependencies
, and they aren't min.js
files, and it
joins all of the 'js' and 'jsx' files into the 'js' extension. That join could
be used in the extensions instead, but it's just there to show you how you
would do it.
Questions
I know it's trying to solve for a lot of different use cases, so if you have any questions about how to implement this in your specific setup, feel free to open an issue. I usually get back to you pretty quickly, but usually no later than 24 hours, as long as I have access to email.
Development
PRs welcome! Make sure you have an updated npm
or the npm scripts won't work.
Tests that run fail if not all the tests pass, if you don't have 100% coverage,
or if the code doesn't pass jshint. I'd like to keep everything the same style,
so feel free to call me out on stuff. If you don't like the coding style, I'm
open for a discussion on it.
To run tests, run npm test
.