bootstrap-loader, Bootstrap styles and scripts pulled into a Webpack bundle

Why the loader exists at all

Bootstrap is distributed as Sass source, and a modern front end build wants to compile that source itself so that the project's variables and mixins can override the framework's. The loader is the piece that makes that work inside Webpack, and it is described as the successor to bootstrap-sass-loader, which was the previous attempt at the same problem. The README headline announces that Webpack 4 and Bootstrap 4 are supported, and the body says Bootstrap 3 and 4 are supported, with the loader using SASS to process CSS styles. It also loads the JavaScript side, not only the styles, and that is the distinguishing feature, because a plain Sass setup gives you the CSS and leaves you to wire the plugins yourself. The audience is a Webpack project that picked Bootstrap and wants the framework's variables under its own control.

Installing means installing a chain of loaders

The installation is a set of npm commands, and the number of them is the first thing to notice. The loader itself is one install, and the peer dependencies are another six.

npm install bootstrap-loader

Then the Bootstrap source and the loader chain have to be added. For Bootstrap 3 the source package is bootstrap-sass, and for Bootstrap 4 it is bootstrap, and the loader chain is css-loader, node-sass, resolve-url-loader, sass-loader, style-loader and url-loader, with imports-loader and exports-loader on top of those for both versions. Bootstrap 4 users probably also want postcss-loader.

npm install --save-dev bootstrap
npm install --save-dev css-loader node-sass resolve-url-loader sass-loader style-loader url-loader
npm install --save-dev imports-loader exports-loader

The peer dependency list in the package manifest is the part to read, because it is where the modern requirements live. It asks for css-loader, node-sass, resolve-url-loader, sass, sass-loader and url-loader, for mini-css-extract-plugin at 0.4.0 or higher, and for webpack at 5.0.0 or higher.

Two ways to load it, and one file that controls the rest

The usage section is short, and the loader can be pulled in two ways. You can require it directly, or you can add it to the entry array in the Webpack config, which the README notes needs Webpack 2.1 beta or higher.

require('bootstrap-loader');

entry: [ 'bootstrap-loader', './app' ]

Configuration is optional, and when you use it the file should sit in the project root with the name .bootstraprc, written in YAML or JSON. The repository ships two default configurations to copy from, .bootstraprc-3-default and .bootstraprc-4-default, and the README says to start from one of them. The rule that catches people out is stated plainly, that config options do not fall back on the defaults once a config file is present, so deleting an option from your file is not the same as leaving it out. If the default location does not work, for example when you want several configurations for different branding or you symlink your node_modules directory, you can pass the absolute path to the .bootstraprc file in the loader request string, using the configFilePath query parameter and the loader's own no-op entry point.

What the configuration actually selects

The configuration file is the heart of the tool, and the README shows both formats. The styleLoaders list is the chain used to process the styles, and the styles object turns individual pieces on, with normalize and print as the examples. The scripts object does the same for the JavaScript side, with alert and button as the examples.

---
# You can use comments here
styleLoaders:
  - style-loader
  - css-loader
  - sass-loader

styles:
  normalize: true
  print: true

scripts:
  alert: true
  button: true

The JSON form carries the same structure and, in the README's example, even shows that comments are tolerated in the JSON file, which is convenient and slightly surprising at the same time. The table of contents lists the rest of the surface, and it is where the Bootstrap 4 specific options live, Tether, PostCSS and the glyphicon alternatives, along with additional configurations for paths to custom assets, incorporating Bootswatch themes, multiple CSS themes, jQuery and icon fonts. The FAQ entry on using Bootstrap mixins and variables is the one to read if the point of the loader is overriding the framework's Sass values rather than merely shipping its CSS.

What is in the package

The repository layout is small and tells you how the loader is assembled. The entry point is loader.js at the root, which is what the main field in the package manifest points to, and beside it sit extractStyles.js for the extracted CSS path and no-op.js, the empty module used when the loader is pointed at a specific configuration file. The sources are in src/ and are compiled with Babel into lib/, which is why the build script is babel --out-dir lib src, and the tests live in node_package/ and are run with babel-tape-runner, piped through tap-spec for the output format. The release machinery is in scripts/, with the release patch, release minor and release major targets calling into it, and the release pipeline is chained through prerelease, which lints, tests, cleans and builds before the version is bumped. The examples directory has three projects, basic, css-modules and multiple-entries, and the repository also carries .babelrc, .eslintrc, .prettierrc, a .travis.yml and the .npmignore, plus the CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md and the LICENSE file, which is MIT.

The version numbers and the two documentation trees

There is an inconsistency in the repository that an adopter should notice rather than discover later. The package manifest says version 4.0.5, while the newest release tags in the project's history are v1.0.9 from 2016-02-29, v1.0.8 from 2016-02-08 and v1.0.7 from 2016-01-26, so the GitHub releases list and the published package version are not telling you the same thing. The peer dependencies tell you which generation of the tool the code expects, and they now demand Webpack 5.0.0 or higher, mini-css-extract-plugin 0.4.0 or higher and the sass package, which is a different world from the Webpack 1 and 2 era the old tags belong to. The README also points at separate documentation for each generation, with the v1 docs on the v1 branch for Webpack v1 and the v2 docs on the 2.2.0 tag, which means the documentation you find first is often not the documentation for the version you installed. The last push was on 2026-07-05, and the repository is not archived.

When this loader is the wrong answer

There are three cases where reaching for this loader is a mistake. The first is Bootstrap 5, which the loader does not support, and a project that has moved to it has no use for the tool. The second is a project that has standardised on a different framework, since the loader's entire value is compiling Bootstrap's Sass with your overrides. The third is a build that has already moved to the modern Sass toolchain, because the peer dependencies ask for node-sass, which is the deprecated implementation, so the loader pushes you towards a dependency your team may have deliberately dropped. There is also a configuration trap worth naming, since the presence of a .bootstraprc file disables the fallback to defaults, so a config file that is missing one key does not inherit the default for that key, it simply loses the feature. The context of the project is worth understanding as well, since the README spends much of its length on ShakaCode's consultancy work, on React on Rails and on their support and coaching programmes, and the loader is the open source piece that keeps that relationship visible.

Editorial conclusion

bootstrap-loader fits a team that decided on Bootstrap 3 or 4 and wants the framework's Sass variables and mixins compiled through its own Webpack build, with the JavaScript plugins selected rather than bundled wholesale. It does not fit a project that has moved to Bootstrap 5, since the supported versions stop at 4, and it does not fit a codebase that has standardised on a different framework or on a different Sass toolchain, since the loader's peer dependencies name node-sass and the classic loader chain. Verify three things before you add it: that your Webpack version satisfies the peer dependency, which the manifest now puts at 5.0.0 or higher, that the Sass implementation you use matches the peer dependency the loader asks for, and whether the version you install matches the documentation you are reading, because the release tags and the package version in the manifest have drifted apart.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. shakacode/bootstrap-loader on GitHub