Demystifying Rails load_defaults: Mastering Configuration Updates

Have you seen this line in your config/application.rb file?config.load_defaults 7.2

Or maybe you've stumbled across an enigmatic-looking initializer like this?👇

config/initializers/new_framework_defaults_7_0.rb

If you weren’t specifically looking for these, you might not even notice they exist.

In this post, I’ll explain what these settings are and guide you through the steps to manage them effectively.

What is config.load_defaults?

config.load_defaults is a configuration setting in rails that helps manage the default configuration values for a specific rails version.

It ensures that your application uses the configuration settings that are appropriate for the version of rails you're running, while maintaining compatibility with previous versions during an upgrade.

When you specify a version with config.load_defaults, rails will load the default settings for that version into your application. This includes changes to things like middleware, default behaviors, and other framework settings that may have evolved over time.

But, why does config.load_defaults exit?

Upgrading a rails application often means dealing with changes in configuration settings, some of which might involve breaking changes. These changes can impact significant parts of your codebase, and updating everything at once can be risky and time-consuming.

This is where config.load_defaults becomes a lifesaver. When you upgrade Rails, you can use config.load_defaults to explicitly specify the version of Rails that determines your application's default configuration settings.

For example, if you're using Rails 7.1, it’s possible that your app's configurations are still using defaults from 7.0 or below. This happens because rails gives you the flexibility to adopt the new defaults gradually. By doing so, your application continues running without any surprising behavior changes, while you methodically transition to newer settings.

This incremental approach allows you to align your app with the latest version’s best practices and performance improvements at your own pace. It’s a great way to minimize disruptions during an upgrade, giving you time to test and address any issues that might arise 😄

What is new_framework_defaults_x_y.rb?

During the version upgrade process, rails creates a special file in your config/initializers directory called something like new_framework_defaults_X_Y.rb (where X and Y matches your target Rails version) when you run rails app:update.

Think of this file as a cheat sheet 📝 for all the new configuration defaults introduced in that rails version. The settings are conveniently listed as commented-out lines, waiting for you to decide when (and if) you want to enable them.

Why is this file helpful?

Adopting new defaults can sometimes lead to changes in behavior that might affect your app. By uncommenting the settings one at a time, you can test each change individually, ensuring your application behaves as expected. This step-by-step approach minimizes risks and gives you the chance to handle compatibility issues without overwhelming your team—or your app 😌

Once you've uncommented all the lines and are confident your app is running smoothly with the new defaults, you can delete this initializer file. At this point, you should also update your config.load_defaults version to reflect the new Rails version.

What if You Can’t Update to a New Setting?

Sometimes, you might find yourself in a situation where updating to a new configuration setting isn't feasible due to specific constraints.

Don’t worry—you can still update your load_defaults version and work around the issue. 👍

Let’s say you’re working with new_framework_defaults_5_1.rb (meaning your Rails version is 5.1, but your load_defaults is still set to 5.0). If you can’t update the following setting because of a restriction:

config.assets.unknown_asset_fallback = false

You can explicitly override this setting by adding it to your config/application.rb file or one of your initializer files, like so:

config.assets.unknown_asset_fallback = true

Once you've added this override, you can safely bump the load_defaults version to 5.1. This ensures your app benefits from other new defaults while maintaining compatibility for the settings you couldn’t update.

⚠️ However, keep in mind that by taking this approach, you’re deviating from the framework’s default behavior. Make sure you document this exception clearly and regularly revisit it to ensure it remains necessary as your app evolves. Strive to align with the defaults whenever possible to keep your application consistent with rails’ best practices.

Wrapping Up

Keeping your app’s configuration aligned with Rails’ defaults is a critical step in maintaining stability and taking advantage of new features. The combination of config.load_defaults and new_framework_defaults_x_y.rb gives you the flexibility to upgrade safely, one step at a time.

By gradually adopting new settings, you reduce the risk of compatibility issues and ensure your app remains modern and efficient. Document any exceptions, revisit them often, and strive to align with Rails best practices. With these tools and strategies, you can confidently keep your app up-to-date and ready for the future.