Styler for Sass

Installation

Please see the appropriate guide for your environment of choice:

a. Ruby on Rails

styler-sass is easy to drop into Rails with the asset pipeline.

In your Gemfile you need to add the styler-sass gem, and ensure that the sass-rails gem is present - it is added to new Rails applications by default.

gem 'styler-sass', '~> 3.3.6'
gem 'sass-rails', '>= 3.2'

bundle install and restart your server to make the files available through the pipeline.

Import Bootstrap styles in app/assets/stylesheets/application.scss:

// "bootstrap-sprockets" must be imported before "bootstrap" and "bootstrap/variables"
@import "bootstrap-sprockets";
@import "bootstrap";

bootstrap-sprockets must be imported before bootstrap for the icon fonts to work.

Make sure the file has .scss extension (or .sass for Sass syntax). If you have just generated a new Rails app, it may come with a .css file instead. If this file exists, it will be served instead of Sass, so rename it:

$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss

Then, remove all the *= require_self and *= require_tree . statements from the sass file. Instead, use @import to import Sass files.

Do not use *= require in Sass or your other stylesheets will not be [able to access][antirequire] the Bootstrap mixins or variables.

Require Bootstrap Javascripts in app/assets/javascripts/application.js:

//= require jquery
//= require bootstrap-sprockets

bootstrap-sprockets and bootstrap should not both be included in application.js.

bootstrap-sprockets provides individual Bootstrap Javascript files (alert.js or dropdown.js, for example), while bootstrap provides a concatenated file containing all Bootstrap Javascripts.

Bower with Rails

When using bootstrap-sass Bower package instead of the gem in Rails, configure assets in config/application.rb:

# Bower asset paths
root.join('vendor', 'assets', 'bower_components').to_s.tap do |bower_path|
  config.sass.load_paths << bower_path
  config.assets.paths << bower_path
end
# Precompile Bootstrap fonts
config.assets.precompile << %r(bootstrap-sass/assets/fonts/bootstrap/[\w-]+\.(?:eot|svg|ttf|woff2?)$)
# Minimum Sass number precision required by bootstrap-sass
::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max

Rails 4.x

Please make sure sprockets-rails is at least v2.1.4.

Rails 3.2.x

bootstrap-sass is no longer compatible with Rails 3. The latest version of bootstrap-sass compatible with Rails 3.2 is v3.1.1.0.

b. Compass without Rails

Install the gem:

$ gem install bootstrap-sass

If you have an existing Compass project:

  1. Require bootstrap-sass in config.rb:

    require 'bootstrap-sass'

Node.js Mincer

If you use [mincer][mincer] with node-sass, import bootstrap like so:

In application.css.ejs.scss (NB .css.ejs.scss):

// Import mincer asset paths helper integration
@import "bootstrap-mincer";
@import "bootstrap";

In application.js:

//= require bootstrap-sprockets

See also this example manifest.js for mincer.

Configuration

Sass

By default all of Bootstrap is imported.

You can also import components explicitly. To start with a full list of modules copy _bootstrap.scss file into your assets as _bootstrap-custom.scss. Then comment out components you do not want from _bootstrap-custom. In the application Sass file, replace @import 'bootstrap' with:

@import 'bootstrap-custom';

Sass: Number Precision

bootstrap-sass requires minimum [Sass number precision][sass-precision] of 8 (default is 5).

Precision is set for Rails and Compass automatically. When using ruby Sass compiler standalone or with the Bower version you can set it with:

::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max

Sass: Autoprefixer

Bootstrap requires the use of [Autoprefixer][autoprefixer]. [Autoprefixer][autoprefixer] adds vendor prefixes to CSS rules using values from Can I Use.

JavaScript

assets/javascripts/bootstrap.js contains all of Bootstrap JavaScript, concatenated in the correct order.

JavaScript with Sprockets or Mincer

If you use Sprockets or Mincer, you can require bootstrap-sprockets instead to load the individual modules:

// Load all Bootstrap JavaScript
//= require bootstrap-sprockets

You can also load individual modules, provided you also require any dependencies. You can check dependencies in the [Bootstrap JS documentation][jsdocs].

//= require bootstrap/scrollspy
//= require bootstrap/modal
//= require bootstrap/dropdown

Fonts

The fonts are referenced as:

"#{$icon-font-path}#{$icon-font-name}.eot"

$icon-font-path defaults to bootstrap/ if asset path helpers are used, and ../fonts/bootstrap/ otherwise.

When using bootstrap-sass with Compass, Sprockets, or Mincer, you must import the relevant path helpers before Bootstrap itself, for example:

@import "bootstrap-compass";
@import "bootstrap";