# bootstrap-rubygem: the Sprockets and Importmaps path to Bootstrap 5

> The bootstrap gem packages Bootstrap 5 for Rails, Hanami and other Sprockets applications, putting SCSS and JavaScript through the asset pipeline instead of a hand-copied vendor directory. It stops at Importmaps and Sprockets, which leaves Webpack and Propshaft projects on a different route.

**twbs/bootstrap-rubygem** — Bootstrap rubygem for Rails / Sprockets / Hanami / etc

- Repository: https://github.com/twbs/bootstrap-rubygem
- Website: https://rubygems.org/gems/bootstrap
- Stars: 2,035 · Forks: 436
- Language: SCSS
- License: MIT
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/twbs-bootstrap-rubygem

## The gem is an asset pipeline bridge, not a second CSS framework

Bootstrap 5 ships as CSS, JavaScript and SCSS source. The `bootstrap` gem exists to put those files inside a Ruby application's compile step so nobody copies a vendor directory by hand. Its homepage is listed as https://rubygems.org/gems/bootstrap, the repository's primary language is SCSS, and the top level holds `assets/`, `lib/`, `bootstrap.gemspec`, `tasks/`, `test/` and a `Rakefile`.

Scope is narrow and stated without hedging: Ruby on Rails on Sprockets or Importmaps, other Sprockets environments, and Hanami, formerly Lotus. A note near the top of the guide rules out one common setup. Newer Rails releases have added further ways to process assets, and this gem is for Importmaps or Sprockets, but not Webpack. Anyone maintaining the Sass builds of Bootstrap 3 or 2 is sent to the separate `bootstrap-sass` project, so this gem is a single major version deep and no further.

## Two recommended Sass engines and the version floors that split them

The gem carries no Sass engine of its own, so the application supplies one, and the four documented options do not cover the same ground. `dartsass-sprockets` is called recommended, with the stated limits of Ruby 2.6+ and Rails 5+. `dartsass-rails` is recommended separately for Rails projects that use Propshaft, which is a different asset path from Sprockets. `cssbundling-rails` drives an external Sass engine. `sassc-rails` is labelled deprecated while staying compatible with Ruby 2.3+ and Rails 4.

Those floors are mutually exclusive rather than free choices. An application on Rails 4 cannot reach the recommended Dart Sass engine at all, and an application still running a Ruby older than 2.6 has no recommended engine either, which leaves the deprecated one as its only listed route. Underneath every option sits a single hard requirement, `sprockets-rails` at v2.3.2 or newer. Autoprefixer is separate and optional: add `autoprefixer-rails` and make sure a JavaScript runtime such as NodeJS exists, for wider browser compatibility.

## A fresh Rails app ships a .css file that shadows the Sass entry point

Begin with the dependency line, which pins the gem to the current 5.3 series:

```ruby
gem 'bootstrap', '~> 5.3.8'
```

After `bundle install` and a server restart, the files are available through the pipeline. The step newcomers miss comes next: a newly generated Rails app contains `app/assets/stylesheets/application.css`, and for as long as that file exists it is served instead of Sass. The remedy is a rename rather than an edit.

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

Then import Bootstrap from that file. The ordering rule survives only as a comment inside the snippet, not in the prose around it.

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

Any `*= require` and `*= require_tree` statements in that file have to go. Keeping them is the documented failure: other stylesheets then cannot reach the Bootstrap mixins and variables.

## Importmap pins and a precompile list that names only one of them

Rails applications on Importmaps pin the JavaScript inside `config/importmap.rb`, and either the readable or the minified Bootstrap file can be pinned, with Popper alongside it:

```ruby
pin "bootstrap", to: "bootstrap.min.js", preload: true
pin "@popperjs/core", to: "popper.js", preload: true
```

Whatever gets pinned also has to be added to `config.assets.precompile`, which the guide places in an initializer:

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

Read the two blocks together and a gap opens up. The prose allows `bootstrap.js` as an alternative pin, yet the precompile example lists `bootstrap.min.js` and `popper.js` only, so a developer who takes the other option gets no matching entry and no note about the omission. A second detail hides in the naming: the same Popper dependency shows up as the gem `popper_js`, as the importmap package `@popperjs/core`, and as the Sprockets require `popper`. Three identifiers, one dependency, and nothing in the guide maps one to another.

## Two Sprockets entry points trade debugging against compile time

On Sprockets, Bootstrap's JavaScript enters through directives in `application.js`. One form exposes individual components:

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

The other form requires the concatenated build:

```js
//= require jquery3
//= require popper
//= require bootstrap
```

The stated reason for the second is faster compilation, and the stated reason for the first is easier debugging. No timing, bundle size or build count sits beside either claim, so the choice remains a preference rather than a measured one. jQuery is optional and only enters here for Rails 5.1+ applications that add `gem 'jquery-rails'`; on every other setup, drop the `jquery3` line. Tooltips and popovers need Popper for positioning, and the gem already depends on it, so nothing extra is installed for those two components.

## One import pulls everything, a copied list pulls only what you keep

A single `@import "bootstrap"` line brings in all of Bootstrap. Selecting components works by copying rather than configuration: copy `_bootstrap.scss` from the gem into the application's own assets as `_bootstrap-custom.scss`, comment out the parts you do not want, then swap the import in the application Sass file.

```scss
@import 'bootstrap-custom';
```

The quote style differs between the two import lines the guide hands over, double quotes in the default example and single quotes in the custom variant. Sass reads both as the same string, so nothing breaks, but the mismatch is a sign these snippets came from different places rather than one maintained block. The copy-and-comment method is manual by design: there is no flag, no environment variable and no per-component switch inside the gem, and overwriting `_bootstrap-custom.scss` with a fresh copy from a newer gem discards every commented-out line without warning.

## The variables template link points at a branch the repository does not list

Bootstrap's Sass variables live in the gem at `assets/stylesheets/bootstrap/_variables.scss`, and that relative path is what the installation guide tells you to open. The guide also carries link definitions at its foot, and one names something else: `https://github.com/twbs/bootstrap-rubygem/blob/master/templates/project/_bootstrap-variables.scss`. That definition never gets referenced in the prose, it targets the `master` branch while the repository's default branch is `main`, and the directory it walks through, `templates/`, is absent from the top level, where `.gitattributes`, `.github/`, `.gitignore`, `Gemfile`, `README.md`, `Rakefile`, `assets/`, `bootstrap.gemspec`, `lib/`, `tasks/` and `test/` sit instead.

Two things follow. Anyone overriding variables should work from the copy inside the gem's `assets/` tree or from a project-level file, not chase that master-branch URL, which may not resolve at all. And the two locations named for variables are not the same file: one is the gem's own `_variables.scss`, the other a project template that the repository listing does not contain.

## What the guide leaves out, and where another project takes over

Three gaps show up without guessing. Manual asset registration for a non-Rails, non-Hanami framework gets a single sentence and no example, leaving a framework without Sprockets or Hanami with nothing concrete to copy. `tasks/` and `Rakefile` appear in the repository while no rake task is documented anywhere in the guide. Rollback gets no procedure either, so editing the Gemfile constraint and running `bundle install` is the entire upgrade path on offer.

The last push was on 2026-09-12 and the repository is not archived, so nothing in the history points to a frozen fork; the gem ships under the MIT license, its release notes live in CHANGELOG.md, and the published versions run v5.3.8 on 2026-01-11, v5.3.3 on 2024-04-29 and v5.0.0 on 2021-05-13.

The alternative the project itself names is `bootstrap-sass`, which covers the Sass builds of Bootstrap 3 and 2 instead of Bootstrap 5. Webpack users get no path here, and Propshaft projects are pointed at `dartsass-rails`, which means the Sprockets directives and the precompile initializer described above do not transfer to them unchanged.

## Conclusion

Adopt it when your app compiles assets through Sprockets or Importmaps and you want Bootstrap 5 built from SCSS instead of copied files; the saving is largest on a Rails project with an older Ruby, where the recommended Dart Sass engines do not apply. Leave it for Webpack. Before you start, open `assets/stylesheets/bootstrap/_variables.scss`, because the guide's only absolute link to a template points at a master branch the repository listing does not contain, and check whether the pinned `~> 5.3.8` line matches the other gem versions your app already carries.

## FAQ

### Does the bootstrap gem work with Webpack?

No. The guide states the gem is for Importmaps or Sprockets, and explicitly not Webpack, because newer Rails versions added other ways to process assets. There is no documented way to feed the gem's files into a Webpack build.

### How do I install Bootstrap in a Rails application?

Add `gem 'bootstrap', '~> 5.3.8'` to the Gemfile together with one Sass engine, keep `sprockets-rails` at v2.3.2 or newer, then run `bundle install` and restart the server. Import the framework from an `.scss` file after renaming any generated `application.css`.

### Why does my Rails application.css stop working after I add the gem?

A newly generated Rails app ships `app/assets/stylesheets/application.css`, and while that file exists it is served instead of Sass. Renaming it to `application.scss` restores the Sass entry point that the gem needs.

### Can I import only some Bootstrap components?

Yes, by copying rather than by configuration. Copy `_bootstrap.scss` into your assets as `_bootstrap-custom.scss`, comment out the components you do not want, and replace the application import with `@import 'bootstrap-custom';`.

### Which Sass engine works on a Rails 4 application?

The listed options split by version. `dartsass-sprockets` is recommended but limited to Ruby 2.6+ and Rails 5+, while the deprecated `sassc-rails` is the one documented as compatible with Ruby 2.3+ and Rails 4.

### Does the bootstrap gem ship Popper.js?

The gem already depends on the `popper_js` gem, which is what Bootstrap tooltips and popovers use for positioning. Under Importmaps the same dependency is pinned as `@popperjs/core`, and under Sprockets it is required as `popper`.

## Sources

- [License: MIT](https://github.com/twbs/bootstrap-rubygem/blob/main/LICENSE)
- [Project website](https://rubygems.org/gems/bootstrap)
- [README](https://github.com/twbs/bootstrap-rubygem/blob/main/README.md)
- [Releases](https://github.com/twbs/bootstrap-rubygem/releases)
- [twbs/bootstrap-rubygem on GitHub](https://github.com/twbs/bootstrap-rubygem)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/twbs-bootstrap-rubygem