How to migrate Rails app from Bootstrap to Bulma

Like many other developers, I have a pet project that I use to learn, practice, and experiment in my own time.

As my most recent career change has been to move from a Javascript-focussed to a Rails-focussed team, my current pet project is, of course, a Rails app.

In this blog post, I will go through my thought process when deciding to migrate the app away from Bootstrap, why I chose Bulma as the new framework, and how to carry out the migration.

If you would rather move straight to the technical steps, feel free to jump to the “How to actually migrate” section.

Bootstrap

At this point, the only detail of interest about the app is that it was initially set up to use the Bootstrap CSS framework.

The reasons for choosing Bootstrap in the first place were totally based on lazyness 😉:

• The objective of the pet project is to allow me to tinker with and get better at Rails, not CSS.
• I had worked extensively with Bootstrap a long, long time ago, and so its syntax was familiar.
• Bootstrap is often quoted as adding unnecessary bloat. But this was of no importance in my project’s case as the app is not intended to ever be live.

And yes, I could have just not used a framework and gone for bare CSS. But, again, CSS is not the point of this project so I chose the solution most likely to speed up the frontend styling.

So far so good!

Why change then? 🤔

Enter dependabot

I am also using this pet project to keep fresh my knowledge of project security and pipelines, acquired at a previous job.

So I have enabled dependabot and added a Github actions workflow for a CI pipeline that runs the unit tests and some linting.

I will probably write about this at some point…

Just now what matters is that dependabot highlighted a vulnerability in the bootstrap-sass gem.

Unfortunately, the gem has not been updated since February 2019 and my app was already using the latest version.

This meant, of course, that I could not simply upgrade the version, I had to find an alternative to Bootstrap.

Why Bulma

There are many CSS frameworks out there, some quite established, others quite new. The best place to start looking for an alternative is Google.

Searching for “alternatives to Bootstrap” provided some useful articles, as well as Reddit and Stackoverflow posts that listed the most popular frameworks and compared their pros and cons.

What I liked about Bulma was that:

• it is Open Source,
• it is actively maintained by hundreds of contributors,
• the last release is very recent,
• it is very light weight,
• it has good documentation, and
• it got good reviews current users.

I know. This last one is a bit simplistic as what works for one project doesn’t necessarily work for another. But it would definitely have been a clear no-no if all the user reviews had been negative!

How to actually migrate

The first thing to do is remove the Bootstrap-related gems from the Rails app.

Uninstall Bootstrap

From the terminal, cd into your project’s folder and type:

gem uninstall bootstrap-sass bootstrap-will_paginate

Then run bundle install to update the environment.

Add Bulma

According to the installation docs, if you are happy to use the Bulma styles as they come, the last step you’ll need to do is add the pre-compiled Bulma stylesheet to your document header:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@1.0.2/css/bulma.min.css">

Otherwise, if like me you want the option to customise styles, you’ll need to add the Bulma npm package into your project.

Before doing that though, you’ll need to install nvm, nodejs, and npm, if your Rails app doesn’t have them yet. Follow the Node official instructions for the best way of doing this.

Use the cssbundling-rails gem

Once your environment is ready, you can install the gem cssbunding-rails. This gem saved me so much time!

cssbunding-rails can be used to install multiple CSS frameworks, not just Bulma. Check out the gem repo to find the whole list. It will also configure the app to compile the CSS styles locally.

To install cssbunding-rails and the Bulma package, run the following from the terminal:

bundle add cssbundling-rails
bin/rails css:install:bulma

Note that running bundle add is equivalent to running gem install followed by bundle install.

Update all classes

The last remaining step is to migrate all the existing CSS classes in the app templates, views and partials from Bootstrap to Bulma.

A bit tedious but necessary.

And, do not forget to update your tests too!

After that, congratulations! All’s done!

A gotcha

Or perhaps not?

After the migration, I could run the app locally but my integration tests were failing with a weird error:

ActionView::Template::Error: 
Error: Invalid CSS after "...-s), var(--l));": expected "}", was "--00-l: var(--bulma" on line 14482:46 of stdin

It turns out I still had the sassc-rails gem in the Gemfile. This compiler gem does not recognise some of the more up-to-date Sass included in Bulma and was causing the errors.

In any case, sassc-rails is not needed as cssbundling-rails does it all for us. So the solution, in the end, was easy:

gem uninstall sassc-rails

That’s it.

Commit, push. All done!