Skip to content

Commit 72bd066

Browse files
committed
Add a section about config.autoload_lib(_once) to the upgrading guide
1 parent a7fa54d commit 72bd066

File tree

1 file changed

+64
-0
lines changed

1 file changed

+64
-0
lines changed

guides/source/upgrading_ruby_on_rails.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,70 @@ to be autoloaded. That is, just reference them.
101101
The `lib` directory is not affected by this flag, it is added to `$LOAD_PATH`
102102
always.
103103

104+
### config.autoload_lib and config.autoload_lib_once
105+
106+
If your application does not have `lib` in the autoload or autoload once paths,
107+
please skip this section. You can find that out by inspecting the output of
108+
109+
```
110+
# Print autoload paths.
111+
bin/rails runner 'pp Rails.autoloaders.main.dirs'
112+
113+
# Print autoload once paths.
114+
bin/rails runner 'pp Rails.autoloaders.once.dirs'
115+
```
116+
117+
If your application already has `lib` in the autoload paths, normally there is
118+
configuration in `config/application.rb` that looks something like
119+
120+
```ruby
121+
# Autoload lib, but do not eager load it (maybe overlooked).
122+
config.autoload_paths << config.root.join("lib")
123+
```
124+
125+
or
126+
127+
```ruby
128+
# Autoload and also eager load lib.
129+
config.autoload_paths << config.root.join("lib")
130+
config.eager_load_paths << config.root.join("lib")
131+
```
132+
133+
or
134+
135+
```ruby
136+
# Same as above, because all eager load paths become autoload paths too.
137+
config.eager_load_paths << config.root.join("lib")
138+
```
139+
140+
That still works, but it is recommended to replace those lines with the more
141+
concise and correct
142+
143+
```ruby
144+
config.autoload_lib(ignore: %w(assets tasks))
145+
```
146+
147+
Please, add to the `ignore` list any other `lib` subdirectories that do not
148+
contain `.rb` files, or that should not be reloaded or eager loaded. For
149+
example, if your applications has `lib/templates`, `lib/generators`, or
150+
`lib/middleware`, you'd add their name relative to `lib`:
151+
152+
```ruby
153+
config.autoload_lib(ignore: %w(assets tasks templates generators middleware))
154+
```
155+
156+
With that one-liner, the (non-ignored) code in `lib` will be also eager loaded
157+
if `config.eager_load` is `true` (the default in `production` mode). This is
158+
normally what you want, but if `lib` was not added to the eager load paths
159+
before and you still want it that way, please opt-out:
160+
161+
```ruby
162+
Rails.autoloaders.main.do_not_eager_load(config.root.join("lib"))
163+
```
164+
165+
The method `config.autoload_lib_once` is the analogous one if the application
166+
had `lib` in `config.autoload_once_paths`.
167+
104168
### `ActiveStorage::BaseController` no longer includes the streaming concern
105169

106170
Application controllers that inherit from `ActiveStorage::BaseController` and use streaming to implement custom file serving logic must now explicitly include the `ActiveStorage::Streaming` module.

0 commit comments

Comments
 (0)