1 Introduction
This guide documents autoloading in zeitwerk
mode, which is new in Rails 6. If you'd like to read about classic
mode instead, please check Autoloading and Reloading Constants (Classic Mode).
In a normal Ruby program, dependencies need to be loaded by hand. For example, the following controller uses classes ApplicationController
and Post
, and normally you'd need to put require
calls for them:
# DO NOT DO THIS. require "application_controller" require "post" # DO NOT DO THIS. class PostsController < ApplicationController def index @posts = Post.all end end
This is not the case in Rails applications, where application classes and modules are just available everywhere:
class PostsController < ApplicationController def index @posts = Post.all end end
Idiomatic Rails applications only issue require
calls to load stuff from their lib
directory, the Ruby standard library, Ruby gems, etc. That is, anything that does not belong to their autoload paths, explained below.
2 Enabling Zeitwerk Mode
The autoloading zeitwerk
mode is enabled by default in Rails 6 applications running on CRuby:
# config/application.rb config.load_defaults "6.0" # enables zeitwerk mode in CRuby
In zeitwerk
mode, Rails uses Zeitwerk internally to autoload, reload, and eager load. Rails instantiates and configures a dedicated Zeitwerk instance that manages the project.
You do not configure Zeitwerk manually in a Rails application. Rather, you configure the application using the portable configuration points explained in this guide, and Rails translates that to Zeitwerk on your behalf.
3 Project Structure
In a Rails application file names have to match the constants they define, with directories acting as namespaces.
For example, the file app/helpers/users_helper.rb
should define UsersHelper
and the file app/controllers/admin/payments_controller.rb
should define Admin::PaymentsController
.
Rails configures Zeitwerk to inflect file names with String#camelize
. For example, it expects that app/controllers/users_controller.rb
defines the constant UsersController
because
"users_controller".camelize # => UsersController
If you need to customize any of these inflections, for example to add an acronym, please have a look at config/initializers/inflections.rb
.
Please, check the Zeitwerk documentation for further details.
4 Autoload paths
We call autoload paths to the list of application directories whose contents are to be autoloaded. For example, app/models
. Such directories represent the root namespace: Object
.
Autoload paths are called root directories in Zeitwerk documentation, but we'll stay with "autoload path" in this guide.
Within an autoload path, file names must match the constants they define as documented here.
By default, the autoload paths of an application consist of all the subdirectories of app
that exist when the application boots ---except for assets
, javascripts
, views
,--- plus the autoload paths of engines it might depend on.
For example, if UsersHelper
is implemented in app/helpers/users_helper.rb
, the module is autoloadable, you do not need (and should not write) a require
call for it:
$ bin/rails runner 'p UsersHelper' UsersHelper
Autoload paths automatically pick any custom directories under app
. For example, if your application has app/presenters
, or app/services
, etc., they are added to autoload paths.
The array of autoload paths can be extended by mutating config.autoload_paths
, in config/application.rb
, but nowadays this is discouraged.
Please, do not mutate ActiveSupport::Dependencies.autoload_paths
, the public interface to change autoload paths is config.autoload_paths
.
5 $LOAD_PATH
Autoload paths are added to $LOAD_PATH
by default. However, Zeitwerk uses absolute file names internally, and your application should not issue require
calls for autoloadable files, so those directories are actually not needed there. You can opt-out with this flag:
config.add_autoload_paths_to_load_path = false
That may speed legit require
calls a bit, since there are less lookups. Also, if your application uses Bootsnap, that saves the library from building unnecessary indexes, and saves the RAM they would need.
6 Reloading
Rails automatically reloads classes and modules if application files change.
More precisely, if the web server is running and application files have been modified, Rails unloads all autoloaded constants just before the next request is processed. That way, application classes or modules used during that request are going to be autoloaded, thus picking up their current implementation in the file system.
Reloading can be enabled or disabled. The setting that controls this behavior is config.cache_classes
, which is false by default in development
mode (reloading enabled), and true by default in production
mode (reloading disabled).
Rails detects files have changed using an evented file monitor (default), or walking the autoload paths, depending on config.file_watcher
.
In a Rails console there is no file watcher active regardless of the value of config.cache_classes
. This is so because, normally, it would be confusing to have code reloaded in the middle of a console session, the same way you generally want an individual request to be served by a consistent, non-changing set of application classes and modules.
However, you can force a reload in the console executing reload!
:
$ bin/rails c Loading development environment (Rails 6.0.0) irb(main):001:0> User.object_id => 70136277390120 irb(main):002:0> reload! Reloading... => true irb(main):003:0> User.object_id => 70136284426020
as you can see, the class object stored in the User
constant is different after reloading.
6.1 Reloading and Stale Objects
It is very important to understand that Ruby does not have a way to truly reload classes and modules in memory, and have that reflected everywhere they are already used. Technically, "unloading" the User
class means removing the User
constant via Object.send(:remove_const, "User")
.
Therefore, if you store a reloadable class or module object in a place that is not reloaded, that value is going to become stale.
For example, if an initializer stores and caches a certain class object
# config/initializers/configure_payment_gateway.rb # DO NOT DO THIS. $PAYMENT_GATEWAY = Rails.env.production? ? RealGateway : MockedGateway # DO NOT DO THIS.
and MockedGateway
gets reloaded, $PAYMENT_GATEWAY
still stores the class object MockedGateway
evaluated to when the initializer ran. Reloading does not change the class object stored in $PAYMENT_GATEWAY
.
Similarly, in the Rails console, if you have a user instance and reload:
> user = User.new > reload!
the user
object is instance of a stale class object. Ruby gives you a new class if you evaluate User
again, but does not update the class user
is instance of.
Another use case of this gotcha is subclassing reloadable classes in a place that is not reloaded:
# lib/vip_user.rb class VipUser < User end
if User
is reloaded, since VipUser
is not, the superclass of VipUser
is the original stale class object.
Bottom line: do not cache reloadable classes or modules.
7 Eager Loading
In production-like environments it is generally better to load all the application code when the application boots. Eager loading puts everything in memory ready to serve requests right away, and it is also CoW-friendly.
Eager loading is controlled by the flag config.eager_load
, which is enabled by default in production
mode.
The order in which files are eager loaded is undefined.
if the Zeitwerk
constant is defined, Rails invokes Zeitwerk::Loader.eager_load_all
regardless of the application autoloading mode. That ensures dependencies managed by Zeitwerk are eager loaded.
8 Single Table Inheritance
Single Table Inheritance is a feature that doesn't play well with lazy loading. Reason is, its API generally needs to be able to enumerate the STI hierarchy to work correctly, whereas lazy loading defers loading classes until they are referenced. You can't enumerate what you haven't referenced yet.
In a sense, applications need to eager load STI hierarchies regardless of the loading mode.
Of course, if the application eager loads on boot, that is already accomplished. When it does not, it is in practice enough to instantiate the existing types in the database, which in development or test modes is usually fine. One way to do that is to throw this module into the lib
directory:
module StiPreload unless Rails.application.config.eager_load extend ActiveSupport::Concern included do cattr_accessor :preloaded, instance_accessor: false end class_methods do def descendants preload_sti unless preloaded super end # Constantizes all types present in the database. There might be more on # disk, but that does not matter in practice as far as the STI API is # concerned. # # Assumes store_full_sti_class is true, the default. def preload_sti types_in_db = \ base_class. select(inheritance_column). distinct. pluck(inheritance_column). compact. each(&:constantize) types_in_db.each do |type| logger.debug("Preloading STI type #{type}") type.constantize end self.preloaded = true end end end end
and then include it in the STI root classes of your project:
# app/models/shape.rb require "sti_preload" class Shape < ApplicationRecord include StiPreload # Only in the root class. end # app/models/polygon.rb class Polygon < Shape end # app/models/triangle.rb class Triangle < Polygon end
9 Troubleshooting
The best way to follow what the loaders are doing is to inspect their activity.
The easiest way to do that is to throw
Rails.autoloaders.log!
to config/application.rb
after loading the framework defaults. That will print traces to standard output.
If you prefer logging to a file, configure this instead:
Rails.autoloaders.logger = Logger.new("#{Rails.root}/log/autoloading.log")
The Rails logger is still not ready in config/application.rb
, but it is in initializers:
# config/initializers/log_autoloaders.rb Rails.autoloaders.logger = Rails.logger
10 Rails.autoloaders
The Zeitwerk instances managing your application are available at
Rails.autoloaders.main Rails.autoloaders.once
The former is the main one. The latter is there mostly for backwards compatibility reasons, in case the application has something in config.autoload_once_paths
(this is discouraged nowadays).
You can check if zeitwerk
mode is enabled with
Rails.autoloaders.zeitwerk_enabled?
11 Opting Out
Applications can load Rails 6 defaults and still use the classic autoloader this way:
# config/application.rb config.load_defaults "6.0" config.autoloader = :classic
That may be handy if upgrading to Rails 6 in different phases, but classic mode is discouraged for new applications.
zeitwerk
mode is not available in versions of Rails previous to 6.0.
Feedback
You're encouraged to help improve the quality of this guide.
Please contribute if you see any typos or factual errors. To get started, you can read our documentation contributions section.
You may also find incomplete content or stuff that is not up to date. Please do add any missing documentation for master. Make sure to check Edge Guides first to verify if the issues are already fixed or not on the master branch. Check the Ruby on Rails Guides Guidelines for style and conventions.
If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.
And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome on the rubyonrails-docs mailing list.