By the way, in case you didn't know, the official Rails Guides website has a section dedicated to upgrades. It's called A Guide for Upgrading Ruby on Rails. The process of upgrading is not actually so difficult if, and only if:
You have a fairly good test coverage. You should have, at the very least, feature specs for the most important parts of your system.
You should upgrade to just one subsequent version at a time, never going straight to the most recent one. For example, If you're in Rails 4.1, you must first upgrade to 4.2, make sure everything works. Then go to 5.0. And only then go to 5.1. Each version has many deprecations, changes in behavior, changes in default boilerplate configuration, added new features. You must attend to each very carefully.
So, what are you missing if you're still in Rails 4.2?
Again, in case you didn't know, the official Rails Guides website also compiles detailed and easy to read Release Notes for each new version. The most recent are the Ruby on Rails 5.1 Release Notes.
Starting a new project
rails new command has a lot of new flags. And I think these are the ones most people will use:
rails new --skip-action-mailer --skip-coffee --webpack=react my_fancy_new_project
You can disable features you don't need such as ActionMailer or actionable. You can disable CoffeeScript. It was cool for a while but now that ES6 exists we should just use it.
Rails 5.1 comes with the support for webpack. But until Rails 5.2 comes up, we need to use the
webpack-dev-server manually in development mode so we can hot reload assets. For that end, I recommend installing good old Foreman. Install it like this:
gem install foreman
And add a
Procfile.dev file to your project with the following content:
web: ./bin/rails s -b 0.0.0.0 -p 3000 webpack: ./bin/webpack-dev-server
And now you can start up your development server like this:
foreman start -f Procfile.dev
In production, you don't need the
webpack-dev-server as the
bin/rails assets:precompile task should be able to compile all the assets you need as static, timestamped files in
Front-end Specific Changes
Now, you can rejoice with Yarn, Webpack, and no more jQuery pre-installed. Samuel Muller has a nice article that summarizes most of these changes in more detail.
No more manually vendoring JS assets in
Let's say that, for some reason, you want jQuery back. You can now just do:
yarn add jquery
And, as usual, you can simply add it to your
1 2 3 4 5
The so-called "support for Yarn in Rails 5.1" boils down to a few wrappers and boilerplate. So you can run
rails yarn:install and have the dependencies installed, but you can just as easily type
yarn and it will install everything you need that is declared in the
Now, the whole magic of the integration comes from the inclusion of the Webpacker gem. It adds a bunch of boilerplate configuration for webpack. And, bonus fact you can include it today in your current Rails 4.2+ projects as well. Just start by adding the webpacker gem to your
# Gemfile gem 'webpacker', '~> 3.0'
bundle install as usual and run:
bundle exec rake webpacker:install
If you didn't use the
--webpack=react flag to the
rails new command, you can add it later. Or you can add Angular as well:
bundle exec rake webpacker:install:angular bundle exec rake webpacker:install:react
You should replace
bundle exec rake for
bin/rails if you're in Rails 5.1.
Adding proper React components is a bit more than the command above though. And the details are more than I want to cover in this post.
Andy Barnov has a good post on how to follow the Rails 5.1 packs convention to add your React components in the pipeline. As he recommends, don't fight the conventions and you should be golden.
Oddly enough, even though I used the
--webpack-react flag to the
rails new I still had to run the following command to bootstrap the webpack and react supports:
But once you do, you will get a new place to add React components, and that's in a proper
hello_react.jsx that it generates for you.
Once upon a time, no one properly knew how to streamline an Asset Pipeline. It was very messy to compile all your assets in a single file with proper cache busting timestamps, but the Sprockets gem did it.
CSS is another matter entirely. The Rails community also created Sass (which then Twitter envied and copied to Less for the Bootstrap framework).
It's easy to see the current landscape and just repeat that Coffee is bad or Sprockets is bad. But for the past 10 years, those tools were the best of breed in a time where people didn't have Yarn, Webpack, React and all the tools that popped up in the past 3 years or so.
One thing that led me to write this post is to highlight that many people ask questions that are mostly answered in the official Rails Guides. Not only on how to install and use the many components of the framework but also how to upgrade and what the new features of each release are. So you should definitely take a better look there.