How to Override Bower Packages

Sage uses gulp to take a list of source files, transform them, then output them to a build directory. Sage also uses the Bower package manager for front-end assets. So the list of source files to be transformed through the build process almost always includes files from Bower packages.

How does Sage know which files to pull from each Bower package? It looks at each dependency’s main property in its respective bower.json. Take a look at the Sass Bootstrap main property and the Less Bootstrap main property. I encourage you to read over the bower.json spec for a more in-depth explanation.

So by default the Bootstrap Bower package imports everything:

[
  "assets/stylesheets/_bootstrap.scss",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.eot",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.svg",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.ttf",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.woff",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.woff2",
  "assets/javascripts/bootstrap.js"
]

Let’s say after thorough analysis you find data that supports the idea that only including the Bootstrap JavaScript modules your project depends on will net your project a non-negligible performance gain. To implement this idea, you need to override what the authors of Bootstrap put in their main property with something that looks like this:

[
  "assets/stylesheets/_bootstrap.scss",
  "assets/javascripts/bootstrap/transition.js",
  "assets/javascripts/bootstrap/alert.js",
  "assets/javascripts/bootstrap/button.js",
  "assets/javascripts/bootstrap/carousel.js",
  "assets/javascripts/bootstrap/collapse.js",
  "assets/javascripts/bootstrap/dropdown.js",
  "assets/javascripts/bootstrap/modal.js",
  "assets/javascripts/bootstrap/tooltip.js",
  "assets/javascripts/bootstrap/popover.js",
  "assets/javascripts/bootstrap/scrollspy.js",
  "assets/javascripts/bootstrap/tab.js",
  "assets/javascripts/bootstrap/affix.js",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.eot",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.svg",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.ttf",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.woff",
  "assets/fonts/bootstrap/glyphicons-halflings-regular.woff2"
]

To do this you use the unofficial overrides property in bower.json. This functionality is documented over at the main-bower-files repo, the wiredep repo, and the asset-builder docs. There is discussion about making this an official bower behavior.

Examples

bootstrap-sass

{
  "overrides": {
    "bootstrap-sass-official": {
      "main": [
        "./assets/stylesheets/_bootstrap.scss",
        "./assets/javascripts/bootstrap/transition.js",
        "./assets/javascripts/bootstrap/alert.js",
        "./assets/javascripts/bootstrap/button.js",
        "./assets/javascripts/bootstrap/carousel.js",
        "./assets/javascripts/bootstrap/collapse.js",
        "./assets/javascripts/bootstrap/dropdown.js",
        "./assets/javascripts/bootstrap/modal.js",
        "./assets/javascripts/bootstrap/tooltip.js",
        "./assets/javascripts/bootstrap/popover.js",
        "./assets/javascripts/bootstrap/scrollspy.js",
        "./assets/javascripts/bootstrap/tab.js",
        "./assets/javascripts/bootstrap/affix.js",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.eot",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.svg",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.ttf",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff2"
      ]
    }
  }
}

bootstrap

{
  "overrides": {
    "bootstrap": {
      "main": [
        "./less/bootstrap.less",
        "./js/transition.js",
        "./js/alert.js",
        "./js/button.js",
        "./js/carousel.js",
        "./js/collapse.js",
        "./js/dropdown.js",
        "./js/modal.js",
        "./js/tooltip.js",
        "./js/popover.js",
        "./js/scrollspy.js",
        "./js/tab.js",
        "./js/affix.js",
        "./fonts/glyphicons-halflings-regular.eot",
        "./fonts/glyphicons-halflings-regular.svg",
        "./fonts/glyphicons-halflings-regular.ttf",
        "./fonts/glyphicons-halflings-regular.woff",
        "./fonts/glyphicons-halflings-regular.woff2"
      ]
    },
  }
}

isotope

The isotope bower.json has caused problems for our users before. At the time of writing the dependencies are incorrectly specified (among other things). This means that js/isotope.js as specified in the main property will not work properly out of the box. So one might wish to use the isotope.pkgd.min.js and with no dependencies.

{
  "overrides": {
    "isotope": {
      "main": ["./dist/isotope.pkgd.min.js"],
      "dependencies": {}
    }
  }
}

Start the discussion on our Discourse

Get our latest updates & occasional tips on building better WordPress sites

Follow @rootswp on Twitter