Railties

Active contributors: rafaelfranca, jonhefner, byroot, eileencodes

Purpose

Railties is the glue: it ships the rails CLI, the application boot machinery, the generator system, the engine/railtie framework, and most of what makes a Rails app feel like a Rails app. It's the only component that depends on every other component.

Source: railties/lib/rails/. ~15,800 lines of lib/ Ruby plus railties/exe/rails (the CLI binary).

Directory layout

railties/
├── exe/
│   └── rails                      # The CLI binary (one-line bootstrap)
├── lib/
│   └── rails/
│       ├── application.rb         # Rails::Application
│       ├── application/
│       │   ├── bootstrap.rb       # First-stage initializers
│       │   ├── configuration.rb   # config.* attributes
│       │   ├── default_middleware_stack.rb
│       │   ├── finisher.rb        # Final initializers
│       │   ├── routes_reloader.rb
│       │   └── dummy_config.rb
│       ├── api/                   # API doc CLI tools
│       ├── autoloaders.rb         # Zeitwerk integration
│       ├── backtrace_cleaner.rb
│       ├── cli.rb                 # Entrypoint for `rails`
│       ├── code_statistics.rb
│       ├── command.rb             # Thor base for sub-commands
│       ├── command/
│       ├── commands/              # Sub-commands (server, console, db, generate, ...)
│       ├── configuration.rb
│       ├── deprecator.rb
│       ├── engine.rb              # Rails::Engine
│       ├── engine/
│       ├── generators/            # Application, model, controller, etc.
│       ├── generators.rb
│       ├── health_controller.rb
│       ├── info.rb / info_controller.rb
│       ├── initializable.rb       # Initializer DSL
│       ├── mailers_controller.rb
│       ├── pwa_controller.rb
│       ├── railtie.rb             # Rails::Railtie
│       ├── ruby_version_check.rb
│       ├── rack/                  # rack-rewrites
│       ├── secrets.rb
│       ├── source_annotation_extractor.rb
│       ├── tasks/
│       ├── test_unit/             # Test runner used by every component
│       └── version.rb
├── test/
└── railties.gemspec

Key abstractions

Constant	File	Purpose
Rails::Application	railties/lib/rails/application.rb	The user's app class (MyApp::Application < Rails::Application)
Rails::Engine	railties/lib/rails/engine.rb	Mountable mini-application; base for Application
Rails::Railtie	railties/lib/rails/railtie.rb	Smallest extension point — register initializers and tasks
Rails::Initializable	railties/lib/rails/initializable.rb	The initializer "name", before: "..." DSL
Rails::Application::Configuration	railties/lib/rails/application/configuration.rb	All config.* attributes
Rails::Generators::Base	railties/lib/rails/generators/base.rb	Base for every generator
Rails::Command::Base	railties/lib/rails/command/base.rb	Thor base for bin/rails sub-commands
Rails::TestUnit::Runner	railties/lib/rails/test_unit/runner.rb	Test runner used by every component's bin/test

Boot sequence

The boot order is documented in the long comment at the top of railties/lib/rails/application.rb:

graph TD
    A["require 'config/boot.rb'"] --> B[require Rails framework]
    B --> C[Define MyApp::Application]
    C --> D[before_configuration callbacks]
    D --> E[Load config/environments/<env>.rb]
    E --> F[before_initialize callbacks]
    F --> G[Run Railtie initializers]
    G --> H[Run application initializers]
    H --> I[Build middleware stack]
    I --> J[to_prepare callbacks]
    J --> K[before_eager_load + eager_load!]
    K --> L[after_initialize callbacks]
    L --> M[App ready]

Rails::Application::Bootstrap (railties/lib/rails/application/bootstrap.rb) declares the earliest initializers (logger, callbacks, autoloading). Rails::Application::Finisher declares the latest ones (eager load, route loading, freeze). Each component's railtie inserts its own initializers between them via before: / after: ordering hints.

Railtie / Engine / Application

The relationship is:

• Rails::Application < Rails::Engine < Rails::Railtie

A railtie is a tiny extension point: register initializers, generators, console hooks, Rake tasks. Every Rails framework defines one (e.g., ActionDispatch::Railtie in actionpack/lib/action_dispatch/railtie.rb).

An engine is a railtie plus a directory layout (app/, config/, lib/) that's mountable. Engines have their own routes, migrations, and assets. Active Storage, Action Mailbox, and Action Text are all engines.

An application is the user's app — an engine that's the root of the app, owns the middleware stack, owns the routes, and runs the boot lifecycle.

Initializers

Rails::Initializable (railties/lib/rails/initializable.rb) provides the initializer DSL:

class MyRailtie < Rails::Railtie
  initializer "my_railtie.set_logger", before: :initialize_logger do |app|
    # ...
  end
end

The Initializable::Collection resolves dependencies via topological sort. To see the resolved order in an app:

bin/rails initializers

Implemented by railties/lib/rails/commands/initializers/initializers_command.rb.

Generators

railties/lib/rails/generators/:

• base.rb — Thor-based base class.
• app_base.rb — common bits between rails new and rails plugin new.
• named_base.rb — for resource-named generators (scaffold, model, etc.).
• actions.rb — high-level helpers (gem, route, environment).
• js_package_manager.rb — Yarn / npm / bun / Importmap.
• database.rb — picks driver-specific scaffolding.
• migration.rb, model_helpers.rb, resource_helpers.rb — scaffolding shared across generators.
• rails/ — the built-in generators (app, model, controller, scaffold, migration, mailer, job, channel, system_test, helper, resource, etc.).
• test_unit/ — generators for test files.
• erb/ — templates for view scaffolding.

bin/rails generate <name> looks up generators across the app's load path; gems can ship their own.

Commands

Thor sub-commands live under railties/lib/rails/commands/:

• server, console, dbconsole
• runner, restart
• generate, destroy, new, plugin
• test, test:system
• routes, unused_routes
• db, query (new in 8.2)
• dev, devcontainer
• secret, credentials, encrypted, initializers
• notes, stats, about, gem_help, help
• middleware, boot, app

Each is a small Thor subclass living in its own subdirectory.

bin/rails query (new in 8.2) is a read-only database console that runs a query against the reading replica role and returns JSON. See railties/CHANGELOG.md.

Autoloading

railties/lib/rails/autoloaders.rb configures the two Zeitwerk loaders Rails uses:

• main — for the application's app/ directories.
• once — for things that should only load once (engine internals).

Rails::Autoloaders::Inflector registers the project's inflections so Zeitwerk can map filenames to constants correctly.

Test runner

railties/lib/rails/test_unit/runner.rb is the Minitest-based runner used by:

• bin/rails test in apps.
• Every component's bin/test (via the 17-line tools/test.rb shim).

Features:

• Line-number filtering (bin/test path:42).
• Test name regex (bin/test -n "/foo/").
• Parallelization (delegates to ActiveSupport::Testing::Parallelization).
• A custom reporter (reporter.rb) that prints relative paths and rerun commands.

Defaults via load_defaults

Rails::Application::Configuration#load_defaults(version) sets the recommended config for a Rails version. Each new defaults block lives at the top of railties/lib/rails/application/configuration.rb. When you opt into 8.1 or 8.2 defaults, you get the curated set of new behaviors enabled.

This is also where new flags introduced via the configuration-flag pattern (see patterns and conventions) are flipped on for a given version.

Integration points

• Every framework component owns a railtie that registers initializers and generators with Railties.
• The rails CLI dispatches to commands via Thor.
• Rails.application.routes is the host RouteSet for Action Pack.
• Rails.application.config is read by every component's railtie.

Entry points for modification

• Adding a sub-command: subclass Rails::Command::Base under railties/lib/rails/commands/<name>/<name>_command.rb. Add tests under railties/test/commands/.
• Adding a generator: subclass Rails::Generators::NamedBase under railties/lib/rails/generators/rails/<name>/. Add tests under railties/test/generators/.
• Adding a configuration option: edit railties/lib/rails/application/configuration.rb. If it ships with a new defaults version, update the matching load_defaults block. Document in guides/source/configuring.md.
• Modifying boot order: add or rearrange initializers in application/bootstrap.rb or application/finisher.rb, or in the relevant component's railtie.rb.

Related pages

• features/initialization-and-railties — boot deep-dive.
• features/generators-and-cli — the generator and command system.
• features/autoloading — Zeitwerk integration.
• reference/configuration — config.* reference.