Customize Bootstrap The Right Way — Maintainable Development

Making a customized bootstrap-based site is great when you start and generally terrible when updating bootstrap or maintaining code. Here’s how to keep up that initial speed that bootstrap offers when it comes time to maintain your site styles.

TLDR: Here’s the code example on github.

Problem: Maintaining customized Bootstrap is a PAIN

Every vanilla Bootstrap site looks JUST like every other Bootstrap site without customization, and that customization generally comes at the cost of maintainability: new version of Bootstrap came out? Sucks to be you! Time for a terrible merge!

Solution: Don’t touch it!

The solution I came up with, and have been using for the last two years at Udacity, is to use a pristine copy of Bootstrap, and write your customizations – everything from variables, to css tweaks, to complete rewrites – separately. Every time a new Bootstrap version comes out, I update the pristine copy and tweak any breaking changes to our own styles. No merge conflicts, no mess.

What’s that look like in practice? Here’s my general directory structure:

The components directory is where all of our bootstrap pieces — both bootstrap and code we write ourselves — lives, and we’ll pull it all together with the shoespooner.less file in the end. (I’m using the LESS version here, but the idea transfers to SASS as well.)

The contents of my_site are the only files we’re actually going to send off to be LESSed. shoespooner.less is the only bootstrap-related file, and it looks something like this:

shoespooner.less contents showing us including bootstrap and our custom overrides.

shoespooner.less contents showing us including bootstrap and our custom overrides.

Because we want our updated variables.less file to run immediately after Bootstrap’s copy, and because most of the files IN Bootstrap directly include variables.less, we add an @include to our version at the bottom of bootstrap’s variables.less that includes our variables file and immediately overwrites (or adds) any variables we might want to use.

Injecting our own variables

Injecting our own variables

Any additional files (like bootstrap_overrides.less) can @include bootstrap’s variables.less and get everything at once.

With Bootstrap customization

With maintainable Bootstrap customization, your life can be this cool.

If you’d like to see an example of overwriting bootstrap in this manner, here’s a quick demo I whipped up.

But where’s the payoff?

Like most things involving code quality/maintenance, doing it right means you don’t end up fighting it later.

When it comes time to update your bootstrap, you just replace the contents of the bootstrap directory, update bootstrap’s variables.less file to include your variables too, and you’re good to go! No more painful merges, no more getting stuck on old versions.


With this method, my team at Udacity has heavily customized Bootstrap, with multiple people writing many many updates. Yet, when a new version of Bootstrap rolls around, we have a relatively painless upgrade path. This saw us through the 2x to 3x migration, as well as multiple following incremental updates, and I’m confident it’ll support us in our upgrades in the future.


3 Comments Customize Bootstrap The Right Way — Maintainable Development

  1. Ford

    Thank you for putting this together. One question: not sure why you had to modify the bootstrap variables.less file with the @import. I could find no reason to do so, making your system even cleaner.

    1. Jacques

      Bootstrap sometimes @imports variables.less — although looking through right now, it appears theme.less is the only one currently doing this. When they do this, you want your variables to overwrite any variables that bootstrap has.
      Because I had to address the existing variables.less imports, and they may add more in the future, it seemed that editing only the one file would be the cleanest and most future-resistant method.

  2. Aaron

    Great article! Has anything changed about your approach since you wrote this? Are you going to use the same process for 4x?

    Also, what’s your process for detecting “breaking changes” – checking the Bootstrap changelog? thorough visual inspection?


Leave a Reply

Your email address will not be published. Required fields are marked *