Ruby on Rails, affectionately known as Rails, remains one of the most popular web development frameworks.

With its convention-over-configuration philosophy, Rails simplifies building robust applications.

But as technology evolves, so do the Rails versions, bringing newer features, improved performance, and enhanced security.

The release of Rails 8 in November 2024 marked another significant milestone for the framework.

As we step into 2025, many developers and teams are planning their migration strategies.

Migrating a Rails application is not a trivial task. It requires a structured approach to ensure the stability of your application and to fully leverage the benefits of the new version.

This article provides a comprehensive checklist to help you navigate a Rails migration in 2025, addressing everything from initial preparation to post-migration optimizations.

1. Understand What’s New in Rails 8

Before you begin, familiarize yourself with the features and changes in Rails 8.

Understanding what the new version brings helps in assessing the migration's impact on your codebase. Key highlights of Rails 8 include:

Hotwire Enhancements: Turbo and Stimulus have been further optimized to handle real-time updates with minimal JavaScript.
Solid Trifecta: A set of integrated tools—Solid Cable, Solid Cache, and Solid Queue—designed to simplify WebSockets, caching, and job queuing. This trio streamlines back-end processes, making modern Rails applications more efficient and scalable.
Propshaft Asset Pipeline: Rails 8 replaces Sprockets with Propshaft, a lightweight and faster asset pipeline.
JavaScript Pinning System: With tools like importmap-rails, Rails 7 onwards enables developers to pin JavaScript dependencies directly, reducing reliance on npm and yarn.
Advanced Query Features: The ActiveRecord library now includes more robust query building and optimization capabilities.
Performance Upgrades: Lazy computation for memory-intensive operations and enhanced caching mechanisms improve performance.
Improved Security Defaults: Enhanced protection against SQL injection, CSRF, and other vulnerabilities.

Review the official Rails 8 release notes to ensure you’re fully informed.

2. Assess Your Application’s Current State

Before diving into migration, perform a thorough audit of your application:

a. Rails Version Check

Determine which Rails version your application currently uses.

If it’s more than two versions behind, consider incremental upgrades rather than jumping directly to Rails 8.

For instance, if you're on Rails 6.0, upgrade to 6.1, then 7.x, and finally to 8.0.

b. Ruby Version Compatibility

Rails 8 requires Ruby 3.2 or higher. Check your current Ruby version by running:

ruby -v

If your version is outdated, plan a Ruby upgrade before migrating Rails.

c. Gemfile Audit

Review your Gemfile to identify outdated or deprecated gems. Use the following command to check for updates:

bundle outdated

Focus on gems that are essential to your application, ensuring they are compatible with Rails 8.

d. Test Coverage

A well-tested application is easier to migrate. Run your test suite and note the coverage percentage. If coverage is low, prioritize writing tests for critical features before proceeding.

3. Create a Migration Plan

Migration is a multi-step process, and having a clear roadmap is essential. Your plan should include:

Timeline: Allocate time for each migration stage, including testing and bug fixing.
Team Responsibilities: Assign specific tasks, such as upgrading gems, updating configurations, and refactoring code, to individual team members.
Backup Strategy: Plan for regular backups to avoid data loss during the migration process.

4. Upgrade Ruby

If your Ruby version is outdated, upgrade it to meet Rails 8 requirements. Here’s how:

a. Use a Ruby Version Manager

Tools like rbenv or RVM simplify Ruby version management. For example, to upgrade with rbenv:

rbenv install 3.2.2  
rbenv global 3.2.2

b. Test Compatibility

After upgrading Ruby, run your application to identify compatibility issues. Pay close attention to deprecated syntax or behavior changes introduced in newer Ruby versions.

5. Upgrade Rails Incrementally

If you're several versions behind Rails 8, incremental upgrades are safer.

Upgrade Rails Incrementally When upgrading Rails, your Gemfile becomes your migration blueprint.

Careful gem specification prevents unexpected conflicts and ensures smooth transitions.

a. Update Rails Gem

To upgrade to the next Rails version, update the rails gem in your Gemfile:

gem 'rails', '~> 7.0' # Adjust version as needed

gem 'bootsnap', '>= 1.4.4'

# Modern asset management
gem 'propshaft'
gem 'importmap-rails'

Then run:

bundle update rails  
rails app:update

b. Run Tests

After each version upgrade, run your test suite to catch issues early.

c. Address Deprecations

Rails provides deprecation warnings to highlight outdated code.

Review these warnings and refactor your code accordingly.

6. Review Application Dependencies

a. Upgrade Gems

Ensure all gems are compatible with Rails 8. Check the gem’s GitHub repository or documentation for compatibility notes.

b. Replace Deprecated Gems

If a gem is no longer maintained, look for modern alternatives. For instance, replace the paperclip gem (now deprecated) with active_storage.

7. Refactor Code for Compatibility

Rails 8 introduces changes that may break older code. Focus on:

a. Assets Pipeline Management

Rails 8 moves away from Sprockets and embraces Propshaft.

This change improves asset precompilation speed and simplifies file organization.

Update your config/application.rb and ensure assets like CSS, JS, and images align with Propshaft's streamlined approach.

Sample config/application.rb

# config/application.rb
class Application < Rails::Application
  # Enable modern asset pipeline
  config.asset_pipeline.enabled = true

  # JavaScript optimization
  config.asset_pipeline.js_compressor = :terser

  # CSS compression strategy
  config.asset_pipeline.css_compressor = :cssbundling
end

In the configuration example, config.asset_pipeline.enabled = true activates this new asset management approach. The :terser and :cssbundling compressors are advanced optimization tools that dramatically reduce asset file sizes. Terser specifically works on JavaScript files, breaking down and reconstructing code to its most compact form without altering its fundamental functionality.

JavaScript Asset Pinning System - Importmap

Additionally, Rails 8's JavaScript asset pinning system offers a modern way to manage JS dependencies.

By using importmap-rails, you can pin libraries directly, removing the need for heavier tools like npm.

This reduces build complexity and improves overall app performance.

9. Optimize Configurations

c. Solid Trifecta Implementation

Rails 8’s Solid Trifecta—Solid Cable, Solid Cache, and Solid Queue — transforms how developers handle WebSockets, caching, and background jobs:

Solid Cable simplifies WebSocket management, making it easier to integrate real-time updates.
Solid Cache offers more flexible and efficient caching strategies tailored to modern apps.
Solid Queue provides a robust queuing system for background jobs, ensuring smoother operations.

10. Deploy to a Staging Environment

Never deploy a newly migrated application directly to production.

Instead:

Deploy to a staging environment identical to production.
Test all critical features, including authentication, payment processing, and external API integrations.
Involve stakeholders in user acceptance testing (UAT).

11. Monitor Post-Migration

Once the migration is live, closely monitor your application for:

a. Error Logs

Use tools like Sentry or Rollbar to track exceptions.

b. Performance Metrics

Analyze server response times, memory usage, and database performance using tools like New Relic or Scout.

c. User Feedback

Encourage users to report issues, and prioritize fixing high-impact bugs.

12. Leverage New Features

Rails 8’s migration isn’t just about compatibility—it’s an opportunity to improve your application by leveraging new features:

Implement Turbo Streams for real-time updates.
Adopt Solid Trifecta tools to enhance your application's efficiency.
Use lazy loading to optimize resource-intensive components.

13. Document the Process

Finally, document the migration process, including challenges faced and solutions implemented. This documentation will serve as a reference for future migrations.

Conclusion

Migrating to Rails 8 in 2025 is a significant undertaking, but the benefits—better performance, modern features, and enhanced security—make it worthwhile.

By following this checklist, you can ensure a smooth transition and position your application for long-term success.

Rails evolves, and so must your applications.

Take this opportunity to not only migrate but also optimize and future-proof your project. Happy coding!

The Ultimate Rails Version Migration Checklist for 2025: A Complete Guide

Table of contents