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.
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:
- 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
Maybe you can find an alternative to Select2 if you want to go away from
- 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.
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
- won't work with Bootstrap 4
Suggestion: Replace the gem with will_paginate-bootstrap4 within the upgrade process.
You will have to update your helper to
will_paginate(collection, renderer: WillPaginate::ActionView::BootstrapLinkRenderer, ...)
- still maintained but has no explicit stylesheet for Bootstrap 4
bootstrap-datepicker3.cssstylesheet 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.
- no longer maintained
- has no explicit stylesheet for Bootstrap 4
bootstrap-clockpicker.cssstylesheet 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.
First you should include the new version into your project and replace the old imports, e.g. with webpack
Your directories should look similar to this:
stylesheets/blocks/ stylesheets/ext/ stylesheets/_environment.scss stylesheets/_variables.scss stylesheets/custom_bootstrap.scss ...
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:
ERROR 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.
// 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!
You can keep very strictly to the official migration guide and should follow it bit by bit.
Many classes have been renamed, e.g.
.badge(for the former badge style you need
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
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.
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!