DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.
This guide documents how to migrate Rails applications from classic
to zeitwerk
mode.
After reading this guide, you will know:
- What are
classic
andzeitwerk
modes - Why switch from
classic
tozeitwerk
- How to activate
zeitwerk
mode - How to verify your application runs in
zeitwerk
mode - How to verify your project loads OK in the command line
- How to verify your project loads OK in the test suite
- How to address possible edge cases
From the very beginning, and up to Rails 5, Rails used an autoloader implemented in Active Support. This autoloader is known as classic
and is still available in Rails 6.x. Rails 7 does not include this autoloader anymore.
Starting with Rails 6, Rails ships with a new and better way to autoload, which delegates to the Zeitwerk gem. This is zeitwerk
mode. By default, applications loading the 6.0 and 6.1 framework defaults run in zeitwerk
mode, and this is the only mode available in Rails 7.
The classic
autoloader has been extremely useful, but had a number of issues that made autoloading a bit tricky and confusing at times. Zeitwerk was developed to address them, among other motivations.
When upgrading to Rails 6.x, it is highly encouraged to switch to zeitwerk
mode because classic
mode is deprecated.
Rails 7 ends the transition period and does not include classic
mode.
Don't :).
Zeitwerk was designed to be as compatible with the classic autoloader as possible. If you have a working application autoloading correctly today, chances are the switch will be easy. Many projects, big and small, have reported really smooth switches.
This guide will help you change the autoloader with confidence.
If for whatever reason you find a situation you don't know how to resolve, don't hesitate to open an issue in rails/rails
and tag @fxn
.
In applications running a Rails version previous to 6.0, zeitwerk
mode is not available. You need to be in at least Rails 6.0.
In applications running Rails 6.x there are two scenarios.
If the application is loading the framework defaults of Rails 6.0 or 6.1 and it is running in classic
mode, it must be opting out by hand. You have to have something similar to this:
# config/application.rb
config.load_defaults 6.0
config.autoloader = :classic # DELETE THIS LINE
As noted, just delete the override, zeitwerk
mode is the default.
On the other hand, if the application is loading old framework defaults you need to enable zeitwerk
mode explictly:
# config/application.rb
config.load_defaults 5.2
config.autoloader = :zeitwerk
In Rails 7 there is only zeitwerk
mode, you do not need to do anything to enable it.
Indeed, the setter config.autoloader=
does not even exist. If config/application.rb
has it, please just delete the line.
To verify the application is running in zeitwerk
mode, execute
bin/rails runner 'p Rails.autoloaders.zeitwerk_enabled?'
If that prints true
, zeitwerk
mode is enabled.
Once zeitwerk
mode is enabled, please run:
bin/rails zeitwerk:check
A successful check looks like this:
% bin/rails zeitwerk:check
Hold on, I am eager loading the application.
All is good!
There can be additional ouput depending on the application configuration, but the last "All is good!" is what you are looking for.
If there's any file that does not define the expected constant, the task will tell you. It does so one file at a time, because if it moved on, the failure loading one file could cascade into other failures unrelated to the check we want to run and the error report would be confusing.
If there's one constant reported, fix that particular one and run the task again. Repeat until you get "All is good!".
Take for example:
% bin/rails zeitwerk:check
Hold on, I am eager loading the application.
expected file app/models/vat.rb to define constant Vat
VAT is an European tax. The file app/models/vat.rb
defines VAT
but the autoloader expects Vat
, why?
This is the most common kind of discrepancy you may find, it has to do with acronyms. Let's understand why do we get that error message.
The classic autoloader is able to autoload VAT
because its input is the name of the missing constant, VAT
, invokes underscore
on it, which yields vat
, and looks for a file called var.rb
. It works.
The input of the new autoloader is the file system. Give the file vat.rb
, Zeitwerk invokes camelize
on vat
, which yields Vat
, and expects the file to define the constant Vat
. That is what the error message says.
Fixing this is easy, you only need to tell the inflector about this acronym:
# config/initializers/inflections.rb
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.acronym "VAT"
end
Doing so affects how Active Support inflects globally. That may be fine, but if you prefer you can also pass overrides to the inflector used by the autoloader:
# config/initializers/zeitwerk.rb
Rails.autoloaders.each do |autoloader|
autoloader.inflector.inflect("vat" => "VAT")
end
With that in place, the check passes 🎉:
% bin/rails zeitwerk:check
Hold on, I am eager loading the application.
All is good!
You can autoload and eager load from a standard structure like
app/models
app/models/concerns
In that case, app/models/concerns
is assumed to be a root directory (because it belongs to the autoload paths), and it is ignored as namespace. So, app/models/concerns/foo.rb
should define Foo
, not Concerns::Foo
.
The Concerns::
namespace worked with the classic autoloader as a side-effect of the implementation, but it was not really an intended behavior. An application using Concerns::
needs to rename those classes and modules to be able to run in zeitwerk
mode.
Some projects want something like app/api/base.rb
to define API::Base
, and add app
to the autoload paths to accomplish that in classic
mode.
Since Rails adds all subdirectories of app
to the autoload paths automatically, we have another situation in which there are nested root directories, so that setup no longer works. Similar principle we explained above with concerns
.
If you want to keep that structure, you'll need to delete the subdirectory from the autoload paths in an initializer:
# config/initializers/zeitwerk.rb
ActiveSupport::Dependencies.autoload_paths.delete("#{Rails.root}/app/api")
If a namespace is defined in a file, as Hotel
is here:
app/models/hotel.rb # Defines Hotel.
app/models/hotel/pricing.rb # Defines Hotel::Pricing.
the Hotel
constant has to be set using the class
or module
keywords. For example:
class Hotel
end
is good.
Alternatives like
Hotel = Class.new
or
Hotel = Struct.new
won't work, child objects like Hotel::Pricing
won't be found.
This restriction only applies to explicit namespaces. Classes and modules not defining a namespace can be defined using those idioms.
In classic
mode you could technically define several constants at the same top-level and have them all reloaded. For example, given
# app/models/foo.rb
class Foo
end
class Bar
end
while Bar
could not be autoloaded, autoloading Foo
would mark Bar
as autoloaded too.
This is not the case in zeitwerk
mode, you need to move Bar
to its own file bar.rb
. One file, one top-level constant.
This affects only to constants at the same top-level as in the example above. Inner classes and modules are fine. For example, consider
# app/models/foo.rb
class Foo
class InnerClass
end
end
If the application reloads Foo
, it will reload Foo::InnerClass
too.
Spring reloads the application code if something changes. In the test
environment you need to enable reloading for that to work:
# config/environments/test.rb
config.cache_classes = false
Otherwise you'll get this error:
reloading is disabled because config.cache_classes is true
This has no performance penalty.
Please make sure to depend on at least Bootsnap 1.4.4.
The Rake task zeitwerk:check
just eager loads, because doing so triggers built-in validations in Zeitwerk.
You can add the equivalent of this to your test suite to make sure the application always loads correctly regardless of test coverage:
require "test_helper"
class ZeitwerkComplianceTest < ActiveSupport::TestCase
test "eager loads all files without errors" do
Zeitwerk::Loader.eager_load_all
rescue => e
flunk(e.message)
else
pass
end
end
require "rails_helper"
RSpec.describe "Zeitwerk compliance" do
it "eager loads all files without errors" do
expect{ Zeitwerk::Loader.eager_load_all }.not_to raise_error
end
end
All known use cases of require_dependency
have been eliminated with Zeitwerk. You should grep the project and delete them.
If your application uses Single Table Inheritance, please see the Single Table Inheritance section of the Autoloading and Reloading Constants (Zeitwerk Mode) guide.
You can now robustly use constant paths in class and module definitions:
# Autoloading in this class' body matches Ruby semantics now.
class Admin::UsersController < ApplicationController
# ...
end
A gotcha to be aware of is that, depending on the order of execution, the classic autoloader could sometimes be able to autoload Foo::Wadus
in
class Foo::Bar
Wadus
end
That does not match Ruby semantics because Foo
is not in the nesting, and won't work at all in zeitwerk
mode. If you find such corner case you can use the qualified name Foo::Wadus
:
class Foo::Bar
Foo::Wadus
end
or add Foo
to the nesting:
module Foo
class Bar
Wadus
end
end
In classic mode, constant autoloading is not thread-safe, though Rails has locks in place for example to make web requests thread-safe.
Constant autoloading is thread-safe in zeitwerk
mode. For example, you can now autoload in multi-threaded scripts executed by the runner
command.
Beware of configurations like
config.autoload_paths += Dir["#{config.root}/lib/**/"]
Every element of config.autoload_paths
should represent the top-level namespace (Object
) and they cannot be nested in consequence (with the exception of concerns
directories explained above).
To fix this, just remove the wildcards:
config.autoload_paths << "#{config.root}/lib"
In classic
mode, if app/models/foo.rb
defines Bar
, you won't be able to autoload that file, but eager loading will work because it loads files recursively blindly. This can be a source of errors if you test things first eager loading, execution may fail later autoloading.
In zeitwerk
mode both loading modes are consistent, they fail and err in the same files.