Upgrading Bootstrap from 2 to 3 (or between any major versions)

When software goes from one major version to another, it usually means one thing: things are going to break.

For CSS/front-end frameworks, that means class names are going to be different, the structure of the HTML is going to be different. Your custom code put on top of Bootstrap will most likely stop working. It’s a pain to do, but once the work is done, you’ll be left with a superior framework that’s being actively maintained and that other developers are building things for.

Who is this guide for

Note that the following techniques are valid to move from any framework to any other framework. It can be from Bootstrap 2 to the upcoming Bootstrap 4 or from Bootstrap 3 to Foundation. This guide assumes you’re using Ruby on Rails, but you can adapt the strategy even if you don’t use any particular framework.

Furthermore, upgrading a whole front-end framework may seem like a daunting task, but the following instructions allow you to do it incrementally, replacing just parts of the framework at the time which is a big plus!

Step 1: Collapse your current framework into distinct files

For Rails, look at where you import or require the main bootstrap file. Most likely you have a = require bootstrap or @import "bootstrap"; somewhere. If you do, open the bootstrap gem (bundle open bootstrap-sass) and copy bootstrap.scss into a bootstrap2.scss (or bootstrap-old.scss) file in your project. Then replace the require or import to use that new file.

Then copy all the files it imports into a bootstrap2 directory (in your vendor directory ideally). Then update the import paths inside bootstrap2.scss to point to that directory.

Repeat for javascript.

You can then remove the gem from your Gemfile.

It is also recommended that you rename any other bootstrap file you may have in the same manner (appending a 2 or -old) so that you know to which version of the framework they belong.

Confirm that step 1 worked and everything behaves the same as before. You can then proceed to add the new framework.

Step 2: Add the newer version or framework to your project

For Rails, add the latest version to your Gemfile: gem 'bootstrap-sass', '~> 3.3.1.0'

Then you need to use a custom bootstrap.scss file to ensure you only activate what you need and what you have fixed. Open the bundle once again and import the new bootstrap.scss file into a bootstrap-custom.scss or bootstrap3.scss file. Then comment out all the imports.

Once again make sure that everything still behaves as expected. You’ll be ready to start the actual upgrade now.

Step 3: Upgrade all the things

Choose one component to upgrade and do it across your whole website. Let’s use buttons as an example.

First thing is to uncomment the buttons import in the new bootstrap-custom.scss file (and any core imports like variables and mixins). Make sure to get rid of the old framework’s code at the same time (comment out or straight out delete it as you won’t use it anymore). The find all occurrences of the old class names or old HTML structure in your website and update it to the new syntax.

Commit your changes and move on to the next component until you’ve ripped out all the old code and replaced it with the new.

You’re done!

Congratulations, you’ve upgraded your front-end framework without any headaches and you can now use all those fancy new components. Now would be a good time to add Bootlint if you’re still using Bootstrap.