Bootstrap Sass Laravel Package

Getting Started

bootstrap-sass is the official Sass port of Bootstrap 2 and 3. It ships the Bootstrap SCSS source and the Bootstrap JS, so it is a source dependency for your asset pipeline rather than a runtime library. It has had no release since 3.4.1 (2019-02-15) and is effectively end-of-life; treat it as a legacy dependency you pin and isolate.

1. Install (pin the version — this package is frozen):

   npm install --save-dev [email protected]
   

   Legacy alternatives: gem 'bootstrap-sass' (Ruby/Sprockets) or a Composer require of twbs/bootstrap-sass for old Laravel projects. Prefer npm so your existing bundler resolves it.

2. Import it once in your main stylesheet, before your own rules:

   // resources/sass/app.scss
   @import "bootstrap-sass/assets/stylesheets/bootstrap";
   

3. Compile with whatever you already use. Laravel Mix:

   mix.sass('resources/sass/app.scss', 'public/css')
      .js('resources/js/app.js', 'public/js');
   

   Webpack/Vite need the package added to Sass includePaths (or use the ~ prefix) so @import "bootstrap" resolves from node_modules.

4. Look here first, in this order:

   • assets/stylesheets/bootstrap/_variables.scss — every knob you can turn (colors, grid, spacing, $enable-* flags).
   • assets/stylesheets/bootstrap/_bootstrap.scss — the canonical import order; copy it when you want partial imports.
   • assets/javascripts/bootstrap.js + bootstrap/*.js — the source of every plugin (modal, dropdown, tooltip, etc.).

First use case: drop the import into app.scss, compile, and confirm you get Bootstrap 3's grid and type scale. Then immediately do the two things you will always need: set $icon-font-path and move your overrides above the import (see below).

Implementation Patterns

Override variables before the import. Bootstrap uses !default, so anything assigned before the import wins:

// 1. your overrides
$brand-primary: #4b0082;
$font-size-base: 15px;
$grid-gutter-width: 24px;
$icon-font-path: "~bootstrap-sass/assets/fonts/bootstrap/";

// 2. then Bootstrap
@import "bootstrap-sass/assets/stylesheets/bootstrap";

Import only what you use. Copy _bootstrap.scss into your own _bootstrap-custom.scss, delete the components you don't need, and import your variables partial first. This is the single biggest win for bundle size on legacy Bootstrap 3 sites.

// _bootstrap-custom.scss
@import "variables";          // your overrides
@import "bootstrap-sass/assets/stylesheets/bootstrap/variables";
@import "bootstrap-sass/assets/stylesheets/bootstrap/mixins";
@import "bootstrap-sass/assets/stylesheets/bootstrap/normalize";
@import "bootstrap-sass/assets/stylesheets/bootstrap/scaffolding";
@import "bootstrap-sass/assets/stylesheets/bootstrap/grid";
// ...just the components you ship

Wire up the JS as a module. The plugins expect jQuery on window:

// resources/js/app.js
window.$ = window.jQuery = require('jquery');
require('bootstrap-sass');            // all plugins, attaches to $.fn
// or selectively:
require('bootstrap-sass/assets/javascripts/bootstrap/dropdown');
require('bootstrap-sass/assets/javascripts/bootstrap/modal');

Bootstrap 3 needs jQuery only (no Popper). Call plugins the usual way after DOM ready: $('[data-toggle="tooltip"]').tooltip().

Theme with a variable map. Keep a single _theme.scss partial of Bootstrap variables and import it from every entry point so admin, marketing, and email templates stay in sync. Use $brand-primary, $navbar-*, $btn-*, $border-radius-base, $grid-breakpoints — not ad-hoc CSS.

Glyphicons font path. If you use the icon set, point $icon-font-path at where your pipeline emits the .woff/.ttf/.eot files (copy them in Mix, or reference node_modules under Webpack). If you're on Font Awesome or SVG icons, set $icon-font-path: false; and skip the font entirely to avoid 404s.

Version-pin and document it. Because there is no 4.x/5.x line here, add a comment in package.json / _theme.scss noting Bootstrap 3.4.1 and the migration target. This package is not a "latest" dependency; it is a frozen one.

Gotchas and Tips

• End-of-life. This package only covers Bootstrap 2/3. It will never support Bootstrap 4/5 APIs, CSS custom properties, or flexbox-era grid classes. For new projects use the bootstrap package (v4/5) and its Dart Sass source; keep bootstrap-sass only for existing Bootstrap 3 apps.
• Modern Sass compatibility is the real pitfall. Bootstrap 3 source relies on @import and / division. Dart Sass (sass) prints deprecation warnings and recent versions error on / division. Pin sass to a compatible range, or add a compatibility layer, or stay on node-sass/older sass for this entry point. Don't assume "it compiles today, it compiles next year."
• Order matters for overrides. A variable set after the @import does nothing because Bootstrap already consumed the !default. Keep overrides in one partial imported first.
• Autoprefixer is required. The SCSS source assumes a prefixing step for vendor prefixes (flex-free Bootstrap 3 mostly needs this for transforms, transitions, gradients). Configure Browserslist in package.json; without it you ship unprefixed CSS to older targets.
• $icon-font-path defaults to a Ruby/Sprockets-style path and will 404 under npm/Webpack unless you override it or use ~-prefixed paths. Verify in the network tab if icons render as empty boxes.
• Tilde vs. includePaths. ~bootstrap-sass/... works in Webpack/Mix; plain bootstrap-sass/... needs the folder on includePaths. Pick one convention project-wide so partial imports don't break.
• jQuery must load before the plugins. If you require('bootstrap-sass') before assigning window.jQuery, plugins silently no-op and data-attributes (data-toggle="modal") stop working. Initialize after DOMContentLoaded and check the console for $ is not defined.
• Don't edit files in node_modules. Fonts, variable tweaks, and component pruning all belong in your own partials. Wrapping the import in your own _bootstrap-custom.scss keeps the package upgrade-safe (moot given EOL, but it makes the eventual migration to Bootstrap 5 far easier).
• Debugging tip: compile with source maps on and inspect the generated CSS to confirm your overrides landed. If a variable didn't take, it was almost certainly declared after the import or shadowed by a more specific !default in a partial you imported out of order.
• Migration path: when you outgrow it, map $brand-primary → $primary, $grid-gutter-width → $grid-gutter-width, and swap markup to Bootstrap 4/5 classes. Do the variable cleanup now and the migration is mostly a find-and-replace plus CSS class rename.