Getting your assets to work when upgrading to Rails 3.1

I was upgrading an app from Rails 3.0 to Rails 3.1 and had some trouble when it came to assets. Here’s how I got it to work.

1. Upgrading to Rails 3.1

Add Rails 3.1 to your Gemfile. Add or change the gem 'rails' line:

gem 'rails', '3.1.0'

Bundle install:

$ bundle install

Run the update task to get your Rails files up to date, but beware! Just overwriting all files will probably mess up your app, so make sure to backup files or take notice of what changes you need to add to the new files before overwriting them. It will ask you what to do:

$ rake rails:update

Now your app should be running Rails 3.1. You can try running it using rails s but it probably won’t look great because we’ve not yet migrated the assets.

2. Migrating your assets

Try switching off the assets pipeline by commenting out the following line in config/application.rb:

# config.assets.enabled = true

Your app should now be running as usual. If it doesn’t, try ironing out any issues before switching on the assets again:

config.assets.enabled = true

We’re now ready to migrate the assets.

First, add this to your Gemfile:

gem 'jquery-rails'
group :assets do
  gem 'sass-rails', "  ~> 3.1.0"
  gem 'coffee-rails', "~> 3.1.0"
  gem 'uglifier'
end

And install:

$ bundle install

Now to the actual migration:

1. Make sure you have the images, javascripts, and stylesheets folders in your app/assets folder.
2. Move all content from public/images into app/assets/images.
3. Move all content from public/javascripts into app/assets/javascripts.
4. Move all content from public/stylesheets into app/assets/stylesheets.

Your javascripts and stylesheets will be compiled into a single application.js and application.css, so add or change this in your app/views/layouts/application.html.erb:

<%= stylesheet_link_tag 'application' %>
<%= javascript_include_tag 'application' %>

To make sure that the assets generator will find all your javascripts and stylesheets, we will include all your javascripts in application.js and all your stylesheets in application.css. Assuming you are using jQuery, you can delete jquery.js and jquery-ui.js as they will be required and inserted automatically. Add the following to the top of app/assets/javascripts/application.js:

//= require jquery
//= require jquery_ujs
//= require_tree .

And to the top of app/assets/stylesheets/application.css:

/*
 *= require_self
 *= require_tree .
*/

Your javascripts and stylesheets will now be included automatically.

At last update all your image paths from /images to /assets. If you’re using the image_tag helper, all paths will be updated automatically.

3. Deploying your assets

Assuming you are deploying using Capistrano, add the following to your config/deploy.rb:

before "deploy:symlink", "assets:precompile"

namespace :assets do
  desc "Compile assets"
  task :precompile, :roles => :app do
    run "cd #{release_path} && rake RAILS_ENV=#{rails_env} assets:precompile"
  end
end

Your assets will now be compiled right before your app is moved into place in your production environment.

Try deploying your app:

$ cap deploy

If the deployment went as expected, great. If you get an error complaining about a missing JavaScript engine, try adding the following to the assets section of your Gemfile:

gem 'therubyracer'

And run the deployment again.

Your assets should now be in place! If you run into other problems, please write a comment below, and I’ll see if I can help.

Follow me on Twitter