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
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
bootstrap-old.scss) file in your project. Then replace the
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.
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', '~> 22.214.171.124'
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
bootstrap3.scss file. Then comment out all
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
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.
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.