The letter A styled as Alchemists logo. lchemists

Putin's War on Ukraine - Watch President Zelenskyy's speech and help Ukraine fight against the senseless cruelty of a dictator!

Published September 10, 2021 Updated February 19, 2023
Ruby Zeitwerk

Zeitwerk is a Ruby gem for auto-loading/reloading of objects within your project and will soon be a core part of Hanami 2.0.0 and Rails 7.0.0. To quote directly from the Zeitwerk’s documentation:

Given a conventional file structure, Zeitwerk is able to load your project’s classes and modules on demand (autoloading), or upfront (eager loading). You don’t need to write require calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and matches Ruby’s semantics for constants.

With the above in mind, I want to focus on using Zeitwerk within pure Ruby projects and/or gems and how Rubysmith can speed up this process for you. ⚡️


When working with Ruby projects and gems, there are two directory structures to keep in mind which depend on the project and gem name chosen.


Basic structures consist of either a standard or underscored project name. For example, if you name your project demo, you’d use the following structure:

├── lib
│  └── demo.rb

…​which would result in the following implementation of demo.rb:

require "zeitwerk"


# Main namespace.
module Demo

Same goes underscored project names like, for example, demo_test:

├── lib
│  └── demo_test.rb

…​which would result in the following implementation of demo_test.rb:

require "zeitwerk"


# Main namespace.
module DemoTest

Notice that in both of the above cases, each project is properly titleized/camelcased appropriately:

  • Titleize: demoDemo

  • Camelcase: demo_testDemoTest

So far I’ve been talking about Ruby projects and gems interchangeably. The reason is that no matter if you are building a pure, stand-alone Ruby project or a Ruby gem, the structure is the same. This is why Zeitwerk::Loader.for_gem is a convenient shortcut for both situations.


There is a slight caveat, though. Behavior is altered when a project name use dashes. Instead, we get a nested directory and object namespace. For example, if you name your project demo-test, you’ll end up with the following structure:

├── lib
│  └── demo
│     └── test.rb

…​which results in the following implementation of demo/test.rb:

require "zeitwerk"
                .tap { |loader| loader.push_dir "#{__dir__}/.." }

module Demo
  # Main namespace.
  module Test

Notice — due to the dash in the project name — we have Test nested within the Demo namespace. Additionally, the corresponding file is structured as demo/test.rb. Finally, we have to teach Zeitwerk to load the project one directory up from where where Zeitwerk is initialized in order to load the entire library.

This is a conventional and standard practice for organizing Ruby projects and gems. You can find this enforced via the following gems:

  • Rubysmith - Focused specifically on building Ruby projects only. Example usage: rubysmith --build demo.

  • Gemsmith - Built for professional gem smithing and a step above what you get with Bundler. Example usage: gemsmith --generate demo.

  • Bundler - Default with all Ruby installations which can be handy for quick and dirty building of gems. Example usage: bundle gem demo.

All three of the gems above share the same behavior as Zeitwerk when it comes to conventional structures for Ruby projects.


In addition to directory structures, Zeitwerk will generate missing module ancestry. Consider the following:

# Nested - What you want to to do.
module One
  module Two
    class Demo

# Flat - What you want to avoid.
class One::Two::Demo

While the flat definition is an antipattern, Zeitwerk will workaround this implementation flaw by ensuring modules One and Two are dynamically created for you. Otherwise, you’d be fighting with constant resolution errors. That said — and even though Zeitwork will resolve this for you — avoid writing code like this because in situations where you end up not using Zeitwerk or removing Zeitwork entirely, you’ll have to contend with this.

Constant Reload and Reference

When using Ruby’s standard require, any code changes applied after the code was required and loaded, would not be picked up. With Zeitwerk, all of this is handled for you so you can have some of the same code reloading functionality as found in web frameworks.

In addition to constant reloading, Zeitwork also makes it possible to reference auto-loaded constants without requiring them first. This is especially handy in projects like ROM or Hanami.


Now that you understand directory structures, namespacing, and constant resolution, we can talk about how Rubysmith can automate your workflow further when building new projects. The great news is Rubysmith has Zeitwerk support built in by default. 🎉 This means you can use Rubysmith to build any of the following example projects:

rubysmith --build demo
rubysmith --build demo_test
rubysmith --build demo-test

You’ll get identical structures, as talked about earlier, each complete with Zeitwerk support by default. In situations you don’t desire Zeitwerk support, you can disable Zeitwerk when building a project. Example:

rubysmith --build demo --no-zeitwerk

…​which yields the following implementation within the lib/demo.rb file:

# Main namespace.
module Demo

Without Zeitwerk support, you’ll have to manually add require statements as you build out more of our implementation. There are definitely use cases where you want this behavior, especially when working on low-level gems where you want few dependencies. For the most part, letting Zeitwerk do the heavy lifting is a nice win and Rubysmith has you covered in that regard!


I hope you’ve enjoyed this brief exploration of the Zeitwerk gem for use in your own Ruby projects. Consider giving Rubysmith a try the next time you are building a Ruby project. You might be pleasantly surprised in the productivity boost you gain from having a tool like this in your back pocket.