Some tips for upgrading Bootstrap from 3 to 4

Recently I made an upgrade from Bootstrap 3 to Bootstrap 4 in a bigger project. Here are some tips how to plan and perform such an upgrade. The effort will scale with the size of the project and its structure. If your stylesheets already follow strict rules, it may take less time to adapt them to the new version.

Preparation

There are several gems and libraries that works well with bootstrap or provide at least stylesheets/plugins to easily integrate the bootstrap theme. But very often they only work with specific version or are no longer maintained.

You should look for alternatives or newer versions for these libraries before you start. Maybe you can upgrade them beforehand which makes the migration easier.

Here are some libraries that I had come across:

Select2 Show archive.org snapshot

• you have to use at least version 4 to work with Bootstrap 4

Suggestion: Upgrade to a newer version before doing the Bootstrap upgrade and test if everything still works as expected. Here is a migration guide for Select2 Show archive.org snapshot

Maybe you can find an alternative to Select2 if you want to go away from jQuery.

simple-navigation Show archive.org snapshot

• works only well BS 2+3, but not above
• there are some forks which say that they include a BS4 renderer, but they didn't work for me.

Suggestion: Remove simple-navigation and simple_navigation_renderers and implement the navigation on your own.
Tip: Add a feature for your navigation bar beforehand and test links and their highlighting (don't forget dropdown submenus!).

After upgrading to Bootstrap 4 you only have to adapt the html to its new structure Show archive.org snapshot

will_paginate-bootstrap Show archive.org snapshot

• won't work with Bootstrap 4

Suggestion: Replace the gem with will_paginate-bootstrap4 Show archive.org snapshot within the upgrade process.

You will have to update your helper to

Copywill_paginate(collection, renderer: WillPaginate::ActionView::BootstrapLinkRenderer, ...)

bootstrap-datepicker Show archive.org snapshot

• still maintained but has no explicit stylesheet for Bootstrap 4
• the bootstrap-datepicker3.css stylesheet looks ok, but does not support the bootstrap variables

Suggestion: If you don't use fancy datepickers you can use the old style. Otherwise you have to look for another datepicker or overwrite the styles by using bootstrap variables.

bootstrap-clockpicker Show archive.org snapshot

• no longer maintained
• has no explicit stylesheet for Bootstrap 4
• the bootstrap-clockpicker.css stylesheet looks ok, but does not support the bootstrap variables

Suggestion: As for the datepicker. If you don't use fancy clockpickers you can use the old style. Otherwise you have to look for another clockpicker or overwrite the styles by using bootstrap variables.

Upgrade

Phase 1

First you should include the new version into your project and replace the old imports, e.g. with webpack

Copyimport 'bootstrap-sass/assets/javascripts/bootstrap.js'

to

Copyimport 'bootstrap/dist/js/bootstrap.bundle.js'

Your directories should look similar to this:

Copystylesheets/blocks/
stylesheets/ext/
stylesheets/_environment.scss
stylesheets/_variables.scss
stylesheets/custom_bootstrap.scss
... 

where custom_bootstrap.scss should start with a copy of node_modules/bootstrap/scss/bootstrap.scss. You can comment out all modules that you don't use in your project, so you do not load the whole package.

Now you can start your webpack-dev-server to see if the packs can be built. You will see a lot of errors like this:

CopyERROR in <SOME_FILE>
  Module build failed:
  background-color: $gray;
    Undefined variable: "$gray".
      in <YOUR_APPLICATION_PATH>/app/webpack/stylesheets/<some_file>.scss (line XX, column YY)
: Failed to compile.

You could collect the missing variables in a block at the end of _variables.scss and set them to their old value. In a later step you can eliminate them bit by bit and use their new versions.

If you have used bootstrap-sass before you may have already overwritten some variables. Move them also to this block at the end of the file, e.g.

Copy// BS3 variables (Not in bootstrap 4 anymore)
$gray-base: #000;
$gray-darker: #222;
$gray-dark: #333;
$gray: #555;
$gray-light: #777;
$gray-lighter: #eee;

Do this until your packs can be built again.

Tip: You should take a look at the sass variables at "~bootstrap/scss/variables". You can tweak a lot with these variables and you can reactivate some BS3 behaviour by overwriting them with the old defaults.

Now you can take a first look at your application. Many of it will be broken. So be prepared. You have to check each page on your own. There is no way around that!

Phase 2 - Migration guide

You can keep very strictly to the official migration guide Show archive.org snapshot and should follow it bit by bit.

Many classes have been renamed, e.g.

• .panel -> .card
• .label -> .badge (for the former badge style you need .badge.badge-pill now)

The breakpoints have also changed. Since they introduced a new one, you have to increase most of them to next one, e.g. *-md will be now *-lg.

The biggest difference of this version is that they reworked almost everything with flexbox.

Inputs have also been reworked very much. So if you use SimpleForm in your project, I would suggest to regenerate the configuration file with rails generate simple_form:install --bootstrap and merge it with your own customizations instead of only renaming the used classes. You could do this before starting with the migration guide, so you don't have to change the configuration file more than once.

At this point your tests could be green for the first time.

Phase 3

In the last phase you should click through your application and look for broken views on your own. Not everthing will be fixed by the migration guide.

You have finished the migration when your application looks great again!