You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide documents how autoloading and reloading works in `zeitwerk` mode.
7
7
8
8
After reading this guide, you will know:
9
9
10
-
* Autoloading modes
11
10
* Related Rails configuration
12
11
* Project structure
13
12
* Autoloading, reloading, and eager loading
@@ -19,7 +18,7 @@ After reading this guide, you will know:
19
18
Introduction
20
19
------------
21
20
22
-
INFO. 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)](autoloading_and_reloading_constants_classic_mode.html).
21
+
INFO. This guide documents autoloading, reloading, and eager loading in Rails applications.
23
22
24
23
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:
25
24
@@ -48,20 +47,7 @@ end
48
47
49
48
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.
50
49
51
-
52
-
Enabling Zeitwerk Mode
53
-
----------------------
54
-
55
-
The autoloading `zeitwerk` mode is enabled by default in Rails 6 applications running on CRuby:
56
-
57
-
```ruby
58
-
# config/application.rb
59
-
config.load_defaults 6.0# enables zeitwerk mode in CRuby
60
-
```
61
-
62
-
In `zeitwerk` mode, Rails uses [Zeitwerk](https://github.com/fxn/zeitwerk) internally to autoload, reload, and eager load. Rails instantiates and configures a dedicated Zeitwerk instance that manages the project.
63
-
64
-
INFO. 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.
50
+
To provide this feature, Rails manages a couple of [Zeitwerk](https://github.com/fxn/zeitwerk) loaders on your behalf.
65
51
66
52
Project Structure
67
53
-----------------
@@ -417,55 +403,10 @@ Rails.autoloaders.once
417
403
418
404
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).
419
405
420
-
You can check if `zeitwerk` mode is enabled with
406
+
The predicate
421
407
422
408
```ruby
423
409
Rails.autoloaders.zeitwerk_enabled?
424
410
```
425
411
426
-
Differences with Classic Mode
427
-
-----------------------------
428
-
429
-
### Ruby Constant Lookup Compliance
430
-
431
-
`classic` mode cannot match constant lookup semantics due to fundamental limitations of the technique it is based on, whereas `zeitwerk` mode works like Ruby.
432
-
433
-
For example, in `classic` mode defining classes or modules in namespaces with qualified constants this way
was not recommended because the resolution of constants inside their body was brittle. It was better to write them in this style:
441
-
442
-
```ruby
443
-
moduleAdmin
444
-
classUsersController < ApplicationController
445
-
end
446
-
end
447
-
```
448
-
449
-
In `zeitwerk` mode that does not matter anymore. You can pick either style.
450
-
451
-
In `classic` mode, the resolution of a constant could depend on load order, the definition of a class or module object could depend on load order, there were edge cases with singleton classes, oftentimes you had to use `require_dependency` as a workaround, .... The list goes on. The guide for `classic` mode documents [these issues](autoloading_and_reloading_constants_classic_mode.html#common-gotchas).
452
-
453
-
All these problems are solved in `zeitwerk` mode. It just works as expected. `require_dependency` should not be used anymore, because it is no longer needed.
454
-
455
-
### Less File Lookups
456
-
457
-
In `classic` mode, every single missing constant triggers a file lookup that walks the autoload paths.
458
-
459
-
In `zeitwerk` mode there is only one pass. That pass is done once, not per missing constant, and so it is generally more performant. Subdirectories are visited only if their namespace is used.
460
-
461
-
### Underscore vs Camelize
462
-
463
-
Inflections go the other way around.
464
-
465
-
In `classic` mode, given a missing constant Rails _underscores_ its name and performs a file lookup. On the other hand, `zeitwerk` mode checks first the file system, and _camelizes_ file names to know the constant those files are expected to define.
466
-
467
-
While in common names these operations match, if acronyms or custom inflection rules are configured, they may not. For example, by default `"HTMLParser".underscore` is `"html_parser"`, and `"html_parser".camelize` is `"HtmlParser"`.
468
-
469
-
### More Differences
470
-
471
-
There are some other subtle differences. Please check the [autoloading section](upgrading_ruby_on_rails.html#autoloading) of the _Upgrading Ruby on Rails_] guide for details.
412
+
is still available in Rails 7 applications, for compatibility with engines may want to support Rails 6.x. It just returns `true`.
0 commit comments