Bower, an assets package manager

Bower is a package manager which allows you to easily include dependencies for your websites. It runs over Git and could be very useful when you develop websites and do not know how to manage your dependencies.

Indeed, you can use the Bower API to select and include a lot of packages. About 2000 Bower components are available. All of them are listed on a website and you can see or search this components. Any types of assets can be included.

Installation

Before installing Bower, you have to install NodeJS and npm. You cannot install Bower without these elements. Bower requires at least node 0.8. Windows users also have to install msysgit correctly.

Next, you can install Bower via the npm command line :

npm install -g bower

Now, Bower is installed and you can use it in all your projects. The bower help command can give you some useful information.

Configuration

In order to configure Bower, you have to create a JSON .bowerrc file in your home directory. You can define several options: the directory to install packaged components, the default JSON file (which is used to include dependencies) and some other settings like additional Bower registries URLs (searchpath option).

{
  "directory": "my_components",
  "json": "bower.json",
  "searchpath": [
    "https://bower.herokuapp.com"
  ]
}

You can overload the .bowerrc file in each project to have a project specific configuration. It will combine the local and global configurations.

Install packages

Bower allows you to select packages. You can use a local or remote Git repository (or endpoint), an URL to a file (zip or tar.gz included)… When it is a git package (Git endpoint or Git repository) you can use Git tags to specify a version.

You can use the bower search command if you want to see all available bower components:

$ bower search jquery
Search results:
    jquery git://github.com/components/jquery.git
    jquery-ui git://github.com/components/jqueryui
    jquery.cookie git://github.com/carhartl/jquery-cookie.git
    jquery-placeholder git://github.com/mathiasbynens/jquery-placeholder.git
    jquery-waypoints git://github.com/imakewebthings/jquery-waypoints.git
    ...

To install packages for one of your project, you have to go in the corresponding repository. Then, you have several choices to install packages.

The bower.json file

The first one is to list all the packages you want to include in a bower.json file in the project’s root repository.

{
  "name": "myProject",
  "version": "1.0.0",
  "dependencies": {
    "font-awesome": "~3.1.1",
    "d3" : "~3.0"
  }
}

In the dependencies part, you can add all packages you want. You can also create a bower.json file for each version of your project if you want. This way, it is easier to manage package versions and dependencies. Then, launch the installation with the following command line :

bower install

This command uses the bower.json file in the current repository.

Given package

Instead of creating a bower.json file, you can install each package with the following command line:

bower install my_package

So, for example, to install Twitter Bootstrap:

bower install bootstrap

You can also specify a Git endpoint or local repository:

bower install https://github.com/blueimp/jQuery-File-Upload.git
bower install ~/my_bower_package

Given package with version

Installing package via the install command line allows you to specify a version (if the package is a Git package).

bower install jquery#2.0.0

Packages installed this way are installed in the components repository by default. Be careful though as you should never directly modify the contents of this directory.

If you want to see all packages included for a project, you can use the following command:

bower list

Now, you can see packages and dependencies with the installed version. The last available version is also specified:

$ bower list
bower discover Please wait while newer package versions are being discovered
myProject
├─┬ bootstrap#2.3.1
│ └── jquery#2.0.0
├── d3#3.0.8 (3.1.6 now available)
├── font-awesome#3.1.1
├── jQuery-File-Upload#8.1.0
└── jquery#2.0.0

Uninstall packages

To uninstall packages, use the following command line :

bower uninstall my_package_name

If you use the bower.json file, remove the package from this file and launch bower install again. It will not remove it, you have to use the bower uninstall command.

Usage

In my case, I want to use Bower in a Rails application. To allow the application to access bower components files I have to specify the location of the components repository in my project’s .bowerrc file :

{
  "directory": "public/my_components",
  "json": "bower.json"
}

Now, when I install package, they are in the public/my_components repository.

For the example, I need jQuery for my website, so I install the package :

bower install jquery#2.0.0

You can notice that the jQuery folder is in public/my_components.

All you need now is to include the package in your page. In my application’s layout, I have to add the following line:

%script{ src: "/my_components/jquery/jquery.js" }

jQuery is now available for your website. You can easily use a lot of packages and select the right versions.

Integration with the Rails assets pipeline

As you can see, Bower looks like Bundler for javascript, stylesheets or image files. In this case, we want to use Bower with Rails and the assets pipeline and there is a gem to help you, bower-rails. This gem allow you to use bower in a rails app and the rails assets pipeline easily.

Before to install the gem, you need NodeJS and bower (>= 0.9). Next, you can add the following line to your Gemfile :

gem "bower-rails", "~> 0.3.1"

Run bundle install to complete the installation.

Now you can use the bower-rails gem. There is a command to create a bower.json file :

rails g bower_rails:initialize

In this new file, you can specify each package you want to include in your project. This file is seperated in two parts, one for the lib directory and one other for the vendor directory.

{
   "lib": {
    "dependencies": {
      "jquery"      : "git://github.com/components/jquery.git"
    }
  },
  "vendor": {
    "dependencies": {
      "three.js"  : "https://raw.github.com/mrdoob/three.js/master/build/three.js"
    }
  }
}

Once you have specified all the packages you want to include, you can run the rake command to install them.

rake bower:install

There is also an update command which update the specified packages.

rake bower:update

Packages are installed in the /vendor/assets/components and the lib/assets/components directories so you have to add them to your application’s assets in your config/application.rb file.

config.assets.paths << Rails.root.join("lib", "assets", "components")
config.assets.paths << Rails.root.join("vendor", "assets", "components")

Now you can use all included packages for your app as you usually do.

Best practice is to add your components directories content to your gitignore file.

More informations are available on the Github page of bower-rails.

Create your own package

Bower allows you to create and register your own package and after that anyone can install it (with the bower install command) and use it.

To register a new package, there must be a valid JSON manifest in the package directory. Your package must be available at a Git endpoint (GitHub for example) and you can use Git tags to specify version. To choose the name of your package, you need to use an available one (first-come, first-served).

Package manifest

As we said, your package manifest must be valid to register your package. There is a command to create the bower.json file :

bower init

You can also create it without this command.

This file defines several options for your package like the name, the version, the dependencies… Here is an example bower.json file :

{
  "name": "my-project",
  "version": "1.0.0",
  "main": "my_package_path/main.css",
  "ignore": [
    "**/*.txt"
  ],
  "dependencies": {
    "jquery": "2.0.0",
  },
  "devDependencies": {
    "my_test_framework": "1.2.0"
  }
}

Finally, the command to register your package is the next one:

bower register my_package_name package_git_endpoint

If you want to unregister your package, there is no way yet but you can request a package to be unregistered on the Github page.

Conclusion

Bower could be a very useful tool when you must include several packages in your website. You can manage versions eeasier than if you downloaded tools files and add them into your project.

You can find more informations about Bower on the Bower’s Github page.

The Synbioz Team