Last updated at Mon, 06 Nov 2017 18:41:56 GMT

Bootstrap 3 is now established and stable  after its release a year and a half ago, but there is still a sizeable number of websites and web applications that are still styled using Bootstrap 2.

If you’re starting to build a web application, especially for quick prototyping, using Bootstrap 3 is the clear option. But, if you already have a mature application, it is likely you have a large amount of code that needs to be refactored.

This refactoring may not be easy as there are a lot of changes with the the recent Bootstrap upgrade; many breaking changes were introduced by the new version. For example, Class names were combined, renamed and even removed, not to mention the new classes that are now included.

The main challenge is that the two cannot live together in the same application. This is mainly a javascript issue but as there is no benefit of having just the css of both (still not a good idea as this will cause a large amount of duplication) it is best to remove all of bootstrap 2 and replace with the newer version.

So what are these changes?

A major change that could easily make the whole of your styling look incorrect is that bootstrap 3 uses “box-sizing: border-box;” A simple example is putting a 1 pixel border on a 100% width div, with content-box. This will result in a width of 100% + 2 pixels. With border-box, it will be 100%, the border will be inside of the box.

There was also a big consolidation with the class names, which can be seen in the image below.


Grid Migration

The grid is now fluid by default. If you need to have a container with a fixed width then you need to use a wrapper to keep it contained.

There is no more span*. Now, there is base column unit named col that is sized using col-lg-* . So instead of span2 you’d now use col col-lg-2. This also works for offsets so offset* is now col-offset-*.

Modal Migration

A major change is that modals are hidden by default, so when converting them you need to remove .hide class from .modal.

The classes .modal-header .modal-body .modal-footer need to be  inside .modal-content which in turn needs to be inside .modal-dialog.

New classes that weren’t in the last version include:


So how do I switch?

Find and replace all uses of bootstrap 2 with the equivalent bootstrap 3. This is a lot of grunt work, searching the files can be trivial if the html is formatted cleanly and contains no templates. It can be done with lots of tools available online including this handy tool.

But the state of your code may not allow for easy swapping of the classes.

In our case,we had a lot of templates, and some of the classes were generated by javascript and others were part of Angular templates. Parsing these is not easy to automate while still getting 100% accuracy.

The method we ended up using is a more long-term approach which allowed for a more continuous deployment of the code.

You need be able to not break production while still doing a migration in a gradual manner.
And how did you achieve this gradual crossover? Prefixing the version of bootstrap to avoid conflicts. By added a prefix to all the class names, both in the class names and the corresponding javascript, you can migrate parts piece by piece, and still have a stable working bootstrap. Once the whole of the bootstrap is prefixed, you can then bring in bootstrap 3.

Both versions can now live together in the application. This allows for a slower migration, but also mark your code with where needs more refactoring as it is obvious due to the prefixed classes.

This may sound like a mammoth task depending on your code base, and it is by no means trivial, but it IS still doable. The way to go about this is to write a script to find all the uses of bootstrap 2 class and to replace them with a prefixed version. This task may be more manual in places if there is auto generated class names in javascript but this most likely will not be an issue with Bootstrap class names most likely.

The next task is to edit the javascript to avoid conflict with Bootstrap 3’s javascript, method names are the same and this will cause havoc in the code base.

Once this is in you will quickly see your success, check all your components are in working order. The best way to see if the behavior of your application is broken would be to have automated testing of the applications behavior using acceptance testing.

Don’t worry if you’re not quite there yet, and check out this other blog post on acceptance testing that can help you out. Good luck!