How to upgrade Rails 6.1 to Rails 7

1. Update rails in gemfile
2. Upgrade rails packages
3. Add sprockets to gemfile
4. Run update rails task
5. Verify framework defaults
6. Verify depreciated methods

How to upgrade an exising application to Rails 7. Note that Rails 7 requires Ruby 2.7.0 or newer.

1. Update rails in gemfile

# old
gem "rails", "~> 6.1.4"

# new
gem "rails", "~> 7.0.0"

In the terminal run:

bundle update

2. Upgrade rails packages

In the package.json file, find all @rails packages and upgrade then one by one. For example:

yarn upgrade @rails/actioncable --latest
yarn upgrade @rails/activestorage --latest
yarn upgrade @rails/request.js --latest

3. Add sprockets to gemfile

When you are using the asset pipeline, assets related errors can pop up when running a rails command.
Example:

# - Don't know how to build task 'assets:precompile'
# - 'method_missing': undefined method `assets'

Add sprockets to the gem file as it's now an optional depedency.

gem "sprockets-rails"

bundle install

4. Run update rails task

bin/rails app:update

This will prompt you file by file to integrate the new rails 7 defaults.

Example:
Overwrite .../config/boot.rb? (enter "h" for help) [Ynaqdhm]
Note: press h to see the menu options.

Go through every file to inspect the difference between the default set-up of rails 7 and your current configuration.

You can open the files in your editor to compare when selecting merge (m). If you run into the following error:
Please specify merge tool to 'THOR_MERGE' env
Run the app:update command again with your editor specified.

For example (vs code)

THOR_MERGE=code bin/rails app:update

After completing the set-up run rails db:migrate to migrate the newly added active storage migration file.

❗️ If you have set-up other environments, non-default enviroments, like staging.rb make sure to update that file too.

5. Verify framework defaults

After completing the bin/rails app:update from the step 4, Rails creates a new_framework_defaults_7.0.rb file in config/initializers. This file helps you to make a big upgrade a little easier by flipping on the new default settings one-by-one in multiple deployments.

The application.rb file's setting load_defaults specifies which rails version's default settings to load. This means you can temporarily utilize the default configuration settings from Rails 6.1 while running Rails 7.

# Initialize configuration defaults for originally generated Rails version.
config.load_defaults 6.1

Then, gradually turn on each setting and verify your application is still working as intended. Once you've switched on every setting, you can remove the new_framework_defaults_7.0.rb and flip the load_defaults version in application.rb to 7.0.

How to turn on Rails 7 framework defaults (part 1)

# Initialize configuration defaults for originally generated Rails version.
config.load_defaults 7.0

6. Verify depreciated methods

Your application might use other depreciated features. Read through the Rails 6.1 to Rails 7 section to identify and fix any methods call or settings that are no longer supported.