Repository files navigation

Bower support for Rails projects. Dependency file is bower.json in Rails root dir or Bowerfile if you use DSL.Check outchangelog for the latest changes and releases.

Requirements

• node (on github)
• bower (>= 0.10.0) installed with npm

NOTE: If you installnode via package manager withsudo apt-get install nodejs you'll also need to installnodejs-legacy withsudo apt-get install nodejs-legacy. See#91

Install

in Gemfile

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

Bower-rails now supports the standardbower package format out-of-the-box. Simply place your bower.json file inside the Rails root directory to start. Using the standard format will default all bower components to be installed under thevendor directory.

To install dependencies into bothlib andvendor directories, run the initializer to generate a custom bower.json:

  rails g bower_rails:initialize json

This will generate aconfig/initializers/bower_rails.rb config file and a special bower.json that combines two standard bower packages into one. Simply specify your dependencies under each folder name to install them into the corresponding directories.

example bower.json file

{"lib": {"name":"bower-rails generated lib assets","dependencies": {"threex":"git@github.com:rharriso/threex.git","gsvpano.js":"https://github.com/rharriso/GSVPano.js/blob/master/src/GSVPano.js"    }  },"vendor": {"name":"bower-rails generated vendor assets","dependencies": {"three.js":"https://raw.github.com/mrdoob/three.js/master/build/three.js"    }  }}

// Bower packages//= require d3/d3//= require underscore/underscore//

The Ruby DSL configuration is a Bowerfile at the project's root with DSL syntax similar to Bundler.

Run the initializer to generate a sample Bowerfile inside the Rails root and aconfig/initializers/bower_rails.rb config file:

  rails g bower_rails:initialize

Example Bowerfile

By default assets are put to./vendor/assets/bower_components directory:

# Puts to ./vendor/assets/bower_componentsasset"backbone"asset"moment","2.0.0"# get exactly version 2.0.0asset"secret_styles","git@github.com:initech/secret_styles"# get from a git repo# get from a git repo using the tag 1.0.0asset"secret_logic","1.0.0",git:"git@github.com:initech/secret_logic"# get from a github repoasset"secret_logic","1.0.0",github:"initech/secret_logic"# get a specific revision from a git endpointasset"secret_logic",github:"initech/secret_logic",ref:'0adff'# get a single fileasset"three.js","https://raw.github.com/mrdoob/three.js/master/build/three.js"

But the default value can be overridden byassets_path method:

assets_path"assets/my_javascripts"# Puts to ./vendor/assets/my_javascripts/bower_componentsasset"backbone"asset"moment"

Theassets_path method can be overridden by an option in agroup call:

assets_path"assets/javascript"# Puts files under ./vendor/assets/js/bower_componentsgroup:vendor,:assets_path=>"assets/js"doasset"jquery"# Defaults to 'latest'asset"backbone","1.1.1"end# Puts files under ./lib/assets/javascript/bower_componentsgroup:libdoasset"jquery"asset"backbone","1.1.1"end

NOTE: Available groups are:lib and:vendor. Others are not allowed according to the Rails convention.NOTE: All the assets should be stored in/assets subdirectory so putting it under./vendor/js directory is unavailable

You can extendmain directive to include some missing files usingmain_filesoption as parameter or in a block:

# via argumentasset"moment","2.10.1",main_files:["./locale/en-gb.js"]# or in blockasset"moment","2.10.1"domain_files["./locale/en-gb.js","./locale/fr.js","./locale/lv.js"]end

And finally, you can specify the assets to be in the devDependencies block:

asset"backbone","1.1.1"# Adds jasmine-sinon and jasmine-matchers to devDependenciesdependency_group:dev_dependenciesdoasset"jasmine-sinon"# Defaults to 'latest'asset"jasmine-matchers"# Defaults to 'latest'end# Explicit dependency group notation ( not necessary )dependency_group:dependenciesdoasset"emberjs"# Defaults to 'latest'end

results in the following bower.json file:

{"name":"dsl-generated-dependencies","dependencies": {"backbone":"1.1.1","angular":"1.2.18",  },"devDependencies": {"jasmine-sinon":"latest","jasmine-matchers":"latest"  }}

NOTE:

• Available dependency groups are:dependencies (default) and:dev_dependencies. Others are not allowed according to the Rails convention.
• In order to install assets on the:dev_dependencies group please runRAILS_ENV=development rake bower:install.

To specify abower resolution useresolution DSL method in your Bowerfile:

resolution"angular","1.2.22"

That will producebower.json like:

{"name" :"dsl-generated-dependencies","dependencies": {"angular":"1.2.22"  },"resolutions": {"angular":"1.2.22"  }}

Change options in yourconfig/initializers/bower_rails.rb:

BowerRails.configuredo |bower_rails|# Tell bower-rails what path should be considered as root. Defaults to Dir.pwdbower_rails.root_path=Dir.pwd# Invokes rake bower:install before precompilation. Defaults to falsebower_rails.install_before_precompile=true# Invokes rake bower:resolve before precompilation. Defaults to falsebower_rails.resolve_before_precompile=true# Invokes rake bower:clean before precompilation. Defaults to falsebower_rails.clean_before_precompile=true# Excludes specific bower components from clean. Defaults to nilbower_rails.exclude_from_clean=['moment']# Invokes rake bower:install:deployment instead of rake bower:install. Defaults to falsebower_rails.use_bower_install_deployment=true# rake bower:install will search for gem dependencies and in each gem it will search for Bowerfile# and then concatenate all Bowerfile for evaluationbower_rails.use_gem_deps_for_bowerfile=true# Passes the -F option to rake bower:install or rake bower:install:deployment. Defaults to false.bower_rails.force_install=true# Change the default directory namebower_rails.bower_components_directory='bower_components'end

If you are using Rails version < 4.0.0 then you are to requirebower_rails.rb initializer manually inapplication.rb:

moduleYourAppNameclassApplication <Rails::Applicationrequire"#{Rails.root}/config/initializers/bower_rails.rb"    ...endend

By default this line is added while running the generator.

Once you are done withbower.json orBowerfile you can run

• rake bower:install to install packages
• rake bower:install:deployment to install packages from bower.json
• rake bower:update to update packages
• rake bower:update:prune to update components and uninstall extraneous packages
• rake bower:list to list all packages
• rake bower:clean to remove all files not listed asmain files (if specified)
• rake bower:resolve to resolverelative asset paths in components
• rake bower:cache:clean to clear the bower cache. This is useful when you know a component has been updated.

If you'd like to pass any bower CLI options to a rake task, like-f,-j, you can simply do:

rake bower:install['-f']

While using Capistrano 3 and Capistrano Rails gem, it's needed to run bower install before assets compile. Add the following code to your deploy.rb, it will runrake bower:install before compiling the assets. CI=true flag is used not to ask for the analytics at the first bower install.

namespace:bowerdodesc'Install bower'task:installdoonroles(:web)dowithinrelease_pathdowithrails_env:fetch(:rails_env)doexecute:rake,'bower:install CI=true'endendendendendbefore'deploy:compile_assets','bower:install'

If you provide a.bowerrc in the rails project root, bower-rails will use it for bower configuration.Some .bowerrc options are not supported:directory,cwd, andinteractive. Bower-railswill ignore thedirectory property and instead will use the automatically generated asset path.

Bower should be installed using npm. Bower can be installed globally (with$ npm install -g bower) or innode_modules in the root directory of your project.

Some bower components (eg.Bootstrap) have relative urls in the CSS files for imports, images, etc. Rails prefers usinghelper methods for linking to assets within CSS. Relative paths can cause issues when assets are precompiled for production.

Remember that you should havebower installed either locally in your project or on a remote server.

Each bower component should follow thebower.json specwhich designates a recommendedmain directive that lists the primary files ofthat component. You may choose to reference these files if you are using the assetpipeline, in which case other extraneous includes of the bower component are not needed.Therake bower:clean task removes every file that isn't listed in themain directive,if the component specifies amain directive. Remember that you can extend themain directiveinruby DSL configuration. Otherwise, the library will remain as bower installed it. It supports wildcardsin files listed inmain directive.