Bower is a package manager for the web. It offers a generic, unopinionated solution to the problem of front-end package management, while exposing the package dependency model via an API that can be consumed by a more opinionated build stack. There are no system wide dependencies, no dependencies are shared between different apps, and the dependency tree is flat.
Bower runs over Git, and is package-agnostic. A packaged component can be made up of any type of asset, and use any type of transport (e.g., AMD, CommonJS, etc.).
View all packages available through Bower's registry.
Bower depends on Node and npm. It's installed globally using npm:
npm install -g bower
Also make sure that git is installed as some bower packages require it to be fetched and installed.
Much more information is available via bower help
once it's installed. This
is just enough to get you started.
Bower offers several ways to install packages:
#####Using the dependencies listed in the current directory's bower.json
bower install
bower install <package>
bower install <package>#<version>
bower install <name>=<package>#<version>
Where <package>
can be any one of the following:
- A name that maps to a package registered with Bower, e.g,
jquery
. ‡ - A public remote Git endpoint, e.g.,
git:https://github.com/someone/some-package.git
. ‡ - A private Git repository, e.g.,
https://github.com/someone/some-package.git
. If the protocol is https, a prompt will ask for the credentials. ssh can also be used, e.g.,[email protected]:someone/some-package.git
and can authenticate with the user's ssh public/private keys. ‡ - A local endpoint, i.e., a folder that's a Git repository. ‡
- A public remote Subversion endpoint, e.g.,
svn+https://package.googlecode.com/svn/
. ‡ - A private Subversion repository, e.g.,
svn+ssh:https://package.googlecode.com/svn/
. ‡ - A local endpoint, i.e., a folder that's an Subversion repository, e.g.,
svn+file:https:///path/to/svn/
. ‡ - A shorthand endpoint, e.g.,
someone/some-package
(defaults to GitHub). ‡ - A URL to a file, including
zip
andtar
files. Its contents will be extracted.
‡ These types of <package>
might have versions available. You can specify a
semver compatible version to fetch a specific release, and lock the
package to that version. You can also use ranges to specify a range of versions.
If you are using a package that is a git endpoint, you may use any tag, commit SHA,
or branch name as a version. For example: <package>#<sha>
. Using branches is not
recommended because the HEAD does not reference a fixed commit SHA.
If you are using a package that is a subversion endpoint, you may use any tag, revision number,
or branch name as a version. For example: <package>#<revision>
.
All package contents are installed in the bower_components
directory by default.
You should never directly modify the contents of this directory.
Using bower list
will show all the packages that are installed locally.
N.B. If you aren't authoring a package that is intended to be consumed by others (e.g., you're building a web app), you should always check installed packages into source control.
A custom install location can be set in a .bowerrc
file using the directory
property. The .bowerrc file should be a sibling of your project's bower.json.
{
"directory": "public/bower_components"
}
To search for packages registered with Bower:
bower search [<name>]
Using just bower search
will list all packages in the registry.
The easiest approach is to use Bower statically, just reference the package's
installed components manually using a script
tag:
<script src="/bower_components/jquery/jquery.js"></script>
For more complex projects, you'll probably want to concatenate your scripts or use a module loader. Bower is just a package manager, but there are plenty of other tools -- such as Sprockets and RequireJS -- that will help you do this.
To uninstall a locally installed package:
bower uninstall <package-name>
On prezto
or oh-my-zsh
, do not forget to alias bower='noglob bower'
or bower install jquery\#1.9.1
Bower is a user command, there is no need to execute it with superuser permissions.
However, if you still want to run commands with sudo, use --allow-root
option.
To use Bower on Windows, you must install msysgit correctly. Be sure to check the option shown below:
Note that if you use TortoiseGit and if Bower keeps asking for your SSH
password, you should add the following environment variable: GIT_SSH - C:\Program Files\TortoiseGit\bin\TortoisePlink.exe
. Adjust the TortoisePlink
path if needed.
Bower supports installing packages from its local cache (without internet connection), if the packages were installed before.
bower install <package-name> --offline
The content of the cache can be listed with:
bower cache list
The cache can be cleaned with:
bower cache clean
Bower can be configured using JSON in a .bowerrc
file.
The current spec can be read
here
in the Configuration
section.
You must create a bower.json
in your project's root, and specify all of its
dependencies. This is similar to Node's package.json
, or Ruby's Gemfile
,
and is useful for locking down a project's dependencies.
NOTE: In versions of Bower before 0.9.0 the package metadata file was called
component.json
rather than bower.json
. This has changed to avoid a name
clash with another tool. You can still use component.json
for now but it is
deprecated and the automatic fallback is likely to be removed in an upcoming
release.
You can interactively create a bower.json
with the following command:
bower init
The bower.json
defines several options:
name
(required): The name of your package.version
: A semantic version number (see semver).main
[string|array]: The primary endpoints of your package.ignore
[array]: An array of paths not needed in production that you want Bower to ignore when installing your package.dependencies
[hash]: Packages your package depends upon in production.devDependencies
[hash]: Development dependencies.private
[boolean]: Set to true if you want to keep the package private and do not want to register the package in future.
{
"name": "my-project",
"version": "1.0.0",
"main": "path/to/main.css",
"ignore": [
".jshintrc",
"**/*.txt"
],
"dependencies": {
"<name>": "<version>",
"<name>": "<folder>",
"<name>": "<package>"
},
"devDependencies": {
"<test-framework-name>": "<version>"
}
}
To register a new package:
- There must be a valid manifest JSON in the current working directory.
- Your package should use semver Git tags.
- Your package must be available at a Git endpoint (e.g., GitHub); remember to push your Git tags!
Then use the following command:
bower register <my-package-name> <git-endpoint>
The Bower registry does not have authentication or user management at this point
in time. It's on a first come, first served basis. Think of it like a URL
shortener. Now anyone can run bower install <my-package-name>
, and get your
library installed.
There is no direct way to unregister a package yet. For now, you can request a package be unregistered.
Bower also makes available a source mapping. This can be used by build tools to easily consume Bower packages.
If you pass the --paths
option to Bower's list
command, you will get a
simple path-to-name mapping:
{
"backbone": "bower_components/backbone/index.js",
"jquery": "bower_components/jquery/index.js",
"underscore": "bower_components/underscore/index.js"
}
Alternatively, every command supports the --json
option that makes bower
output JSON. Command result is outputted to stdout
and error/logs to
stderr
.
Bower provides a powerful, programmatic API. All commands can be accessed
through the bower.commands
object.
var bower = require('bower');
bower.commands
.install(['jquery'], { save: true }, { /* custom config */ })
.on('end', function (installed) {
console.log(installed);
});
bower.commands
.search('jquery', {})
.on('end', function (results) {
console.log(results);
});
Commands emit four types of events: log
, prompt
, end
, error
.
log
is emitted to report the state/progress of the command.prompt
is emitted whenever the user needs to be prompted.error
will only be emitted if something goes wrong.end
is emitted when the command successfully ends.
For a better of idea how this works, you may want to check out our bin file.
When using bower programmatically, prompting is disabled by default. Though you can enable it when calling commands with interactive: true
in the config.
This requires you to listen for the prompt
event and handle the prompting yourself. The easiest way is to use the inquirer npm module like so:
var inquirer = require('inquirer');
bower.commands
.install(['jquery'], { save: true }, { interactive: true })
// ..
.on('prompt', function (prompts, callback) {
inquirer.prompt(prompts, callback);
});
NOTE: Completion is still not implemented for the 1.0.0 release
Bower now has an experimental completion
command that is based on, and works
similarly to the npm completion. It is
not available for Windows users.
This command will output a Bash / ZSH script to put into your ~/.bashrc
,
~/.bash_profile
, or ~/.zshrc
file.
bower completion >> ~/.bash_profile
Have a question?
- StackOverflow
- Mailinglist - [email protected]
- #bower on Freenode
Anyone and everyone is welcome to contribute. Please take a moment to review the guidelines for contributing.
Thanks for assistance and contributions:
@addyosmani, @ahmadnassri, @angus-c, @borismus, @carsonmcdonald, @chriseppstein, @danwrong, @davidmaxwaterman, @desandro, @hemanth, @isaacs, @josh, @jrburke, @kennethklee, @marcelombc, @marcooliveira, @mklabs, @MrDHat, @richo, @rvagg, @ryanflorence, @SlexAxton, @sstephenson, @tomdale, @uzquiano, @visionmedia, @wagenet, @wycats
Copyright (c) 2014 Twitter and other contributors
Licensed under the MIT License