Bootstrap Ruby Gem

To use Bootstrap 5 in a Ruby on Rails application, add the bootstrap gem to your Gemfile. This gem requires a Sass engine to process styles.

Required Sass Engines (choose one):

• dartsass-sprockets (Recommended for Ruby 2.6+ and Rails 5+)
• dartsass-rails (Recommended for Rails projects using Propshaft)
• cssbundling-rails (External Sass engine)
• sassc-rails (Deprecated, compatible with Ruby 2.3+ and Rails 4)

Prerequisites:

• sprockets-rails must be at least v2.3.2.
• For browser compatibility, add autoprefixer-rails and ensure a JavaScript runtime (like NodeJS) is installed.
• For Bootstrap JavaScript tooltips/popovers, the gem includes popper_js, but you may want to add jquery-rails if you require jQuery support.

If using Rails Importmaps, pin bootstrap.min.js and popper.js in config/importmap.rb. You must also add these files to the asset precompilation list in config/initializers/assets.rb to ensure they are available.

# config/importmap.rb
pin "bootstrap", to: "bootstrap.min.js", preload: true
pin "@popperjs/core", to: "popper.js", preload: true

# config/initializers/assets.rb
Rails.application.config.assets.precompile += %w(bootstrap.min.js popper.js)

To use Bootstrap's Sass features (variables and mixins), import it in your app/assets/stylesheets/application.scss file.

Important:

• Ensure your file has a .scss (or .sass) extension. If you have application.css, rename it to application.scss.
• Remove all *= require and *= require_tree statements from the file. Use @import instead. Using *= require prevents access to Bootstrap mixins and variables.
• Custom Bootstrap variables must be defined or imported before the @import "bootstrap"; line.

// Custom bootstrap variables must be set or imported *before* bootstrap.
@import "bootstrap";

If using Sprockets, add the Bootstrap dependencies and the Bootstrap assets to your app/assets/javascripts/application.js using //= require statements.

Option 1: Individual components (better for debugging)

//= require jquery3
//= require popper
//= require bootstrap-sprockets

Option 2: Concatenated Bootstrap (faster compilation)

//= require jquery3
//= require popper
//= require bootstrap

By default, @import "bootstrap"; imports the entire framework. To import only specific components to reduce file size:

1. Copy the assets/stylesheets/_bootstrap.scss file from the gem into your project's assets folder as _bootstrap-custom.scss.
2. Open _bootstrap-custom.scss and comment out the components you do not want to use.
3. In your main application Sass file, replace @import 'bootstrap'; with @import 'bootstrap-custom';.

The bootstrap-rubygem requires a Sass engine to process its assets. If you encounter a LoadError stating that a Sass engine is missing, you must add one of the following gems to your project's dependencies:

• dartsass-sprockets
• sassc-rails
• dartsass-rails
• cssbundling-rails

Call Bootstrap.load! to automatically detect your Ruby environment and register the necessary asset paths. The method detects and configures support for:

• Rails: Registers the Bootstrap Rails engine.
• Hanami: Adds Bootstrap assets to Hanami::Assets.sources.
• Sprockets: Appends Bootstrap stylesheets and javascripts to the Sprockets load paths.
• Legacy Sass gem: Appends the Bootstrap stylesheets path to Sass.load_paths and ensures Sass number precision is set to at least 6.

Note: The gem calls Bootstrap.load! automatically upon being required.

You can use the following predicate methods to check if the Bootstrap gem has detected a specific framework or asset pipeline in your current environment:

• Bootstrap.rails?: Returns true if Rails is defined.
• Bootstrap.hanami?: Returns true if Hanami is defined.
• Bootstrap.sprockets?: Returns true if Sprockets is defined.

The Bootstrap module provides helper methods to locate the gem's internal asset directories. These are useful if you need to reference Bootstrap's source files manually in your application configuration.

• Bootstrap.gem_path: The root directory of the Bootstrap gem.
• Bootstrap.assets_path: The directory containing all gem assets.
• Bootstrap.stylesheets_path: The directory containing Bootstrap's CSS/Sass files.
• Bootstrap.javascripts_path: The directory containing Bootstrap's JavaScript files.