Twbs Sass Rails

An opinionated gem which brings Bootstrap for Sass 3.4.1, Font Awesome 4.7.0 and Respond.js assets into your Rails application.

Deprecated

We need this gem for some old projects that require Bootstrap 3.

In our new development stack, we are loading Bootstrap and Font Awesome via yarn.

Quick start

Add the gem to your Gemfile

gem 'twbs_sass_rails', '~> 10.0'

Run the generator

$ rails g twbs_sass_rails:install

Rails 5.1.x

Rails 5.1 drops jQuery as a default dependency.

If you need the JavaScript part of Bootstrap, add to your Gemfile

gem 'jquery-rails', '~> 4.3'

and replace //= require rails-ujs in your application JavaScript manifest with

//= require jquery
//= require jquery_ujs

Customization

Variables

Use twbs-variables.css.scss to override Bootstrap defaults:

/* New variables */
$flat-ui-emerald:       #2ecc71;
$flat-ui-nephritis:     #27ae60;

$flat-ui-peter-river:   #3498db;
$flat-ui-belize-hole:   #2980b9;

/* Overrides */
$brand-primary:         $flat-ui-belize-hole;
$brand-success:         $flat-ui-nephritis;

/* Do not edit below this line */
@import "twbs/bootstrap/variables";

NOTE: Remember to import twbs-variables instead of twbs/bootstrap/variables in any new SCSS file. WARNING: Leave @import "twbs/bootstrap/variables"; at the very end of the file.

Glyphs

Twbs Sass Rails comes with Glyphicons and Fontawesome, both disabled by default. Edit your twbs.css.scss to enable them.

Use Glyphicons:

@import "twbs/bootstrap/glyphicons";
//@import "fontawesome/font-awesome";

Use FontAwesome:

//@import "twbs/bootstrap/glyphicons";
@import "fontawesome/font-awesome";

Bootstrap theme

If you want to use the Bootstrap theme, uncomment //@import "twbs/bootstrap/theme" in your twbs.css.scss.

Customize SCSS components

If you want to exclude some SCSS components, remove @import "twbs/bootstrap"; from your twbs.css.scss and add the components you need, e.g.:

/* Use twbs-variables to define new variables and override Bootstrap defaults.
 * Import "twbs-variables" instead of "twbs/bootstrap/variables"
 * in each new stylesheet.
 */
@import "twbs-variables";

/* Start editing below this line */
// Core variables and mixins
@import "twbs/bootstrap/variables";
@import "twbs/bootstrap/mixins";

// Reset
@import "twbs/bootstrap/normalize";
@import "twbs/bootstrap/print";
/* ... */

Take a look at the whole list of SCSS components. Respect the order of the files and remember to edit paths.

Customize Javascript components

If you want to exclude some Javascript components, remove //= require twbs/bootstrap from twbs.js.coffee and add the components you need, e.g:

/* ... */
//= require jquery_ujs
//= require twbs/bootstrap/transition
//= require twbs/bootstrap/alert
//= require twbs/bootstrap/button
//= require turbolinks
/* ... */

Take a look at the whole list of Javascript components. Respect the order of the files and remember to edit paths.

Testing

Twbs Sass Rails uses Appraisal for testing against multiple gem dependency versions.

$ appraisal install; appraisal update # Make sure your appraisals are installed and up to date
$ appraisal rake

Contributing

Please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.

More over, if your pull request contains patches or features, you must include relevant unit tests.

Editor preferences are available in the editor config for easy use in common text editors. Read more and download plugins at https://editorconfig.org/.

Versioning

For transparency and insight into our release cycle, and for striving to maintain backward compatibility, Twbs Sass Rails will be maintained under the Semantic Versioning guidelines as much as possible. Twbs Sass Rails will not follow Bootstrap's version number.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch

For more information on SemVer, please visit https://semver.org/.

Authors

Geremia Taglialatela

Cesidio Di Landa