Skip to content
W3S101

Ruby on Rails - Directory Structure

Ruby on Rails - Modern Directory Structure

Section titled “Ruby on Rails - Modern Directory Structure”

When you create a new Rails application using the rails new <app_name> command, Rails generates a standard directory structure. This convention is a cornerstone of Rails development, promoting consistency and making it easier to navigate and understand different Rails projects.

Let’s explore the typical top-level directory structure of a modern Rails application, for example, one created with rails new my_app:

After running rails new my_app, you would navigate into the application’s root directory:

$ cd my_app
$ ls # or 'dir' on Windows

You will find a set of directories and files. Here’s an overview of the most important ones:

  • app/: This is where most of your application-specific code lives. It’s the heart of your Rails project.
    • app/assets/: Contains static assets like stylesheets (app/assets/stylesheets/), images (app/assets/images/), and potentially custom fonts. Rails’ asset pipeline processes these.
    • app/channels/: For Action Cable, used for real-time features with WebSockets.
    • app/controllers/: Holds your controller classes. Controllers handle web requests, interact with models, and select views to render.
    • app/helpers/: Contains helper modules that provide utility methods available in your views to keep view logic clean.
    • app/javascript/: (Common with modern JS bundling like esbuild or Webpacker) Contains your JavaScript code, often organized into packs or components.
    • app/jobs/: For Active Job, used to define background jobs that can be processed by queuing backends.
    • app/mailers/: Holds your Action Mailer classes, used for sending emails.
    • app/models/: Contains your Active Record model classes, which represent your application’s data and business logic.
    • app/views/: Holds your view templates (e.g., ERB files). They are organized into subdirectories named after their corresponding controllers.
  • - **`app/views/layouts/`**: Contains layout files that define the common structure (like headers and footers) for your views.
  • bin/: Contains executable scripts for your application, including:
    • bin/rails: The primary command-line interface for Rails tasks (e.g., starting the server, running generators, migrations).
    • bin/bundle: A binstub for Bundler, ensuring you use the correct gem versions.
    • bin/setup: A script to set up the application for the first time (e.g., install dependencies, create database, run migrations).
    • bin/dev: (In newer Rails versions) A script to start development servers (e.g., Rails server, JS bundler, CSS watcher).
  • config/: Contains configuration files for your application.
    • config/application.rb: Core application configuration.
    • config/database.yml: Database connection settings.
    • config/environment.rb: Rails environment loading point.
    • config/environments/: Environment-specific configurations (development.rb, test.rb, production.rb).
    • config/initializers/: Ruby files that run when the application starts, used for configuring gems or framework settings.
    • config/locales/: Internationalization (i18n) files for translations.
    • config/routes.rb: Defines your application’s URL-to-controller action mappings.
  • db/: Contains database-related files.
    • db/migrate/: Holds database migration files, which allow you to evolve your database schema over time.
    • db/schema.rb: A representation of your current database schema, automatically generated by Rails.
    • db/seeds.rb: A script to populate your database with initial or sample data.
  • lib/: For your own library code that doesn’t fit neatly into app/.
    • lib/assets/: Additional assets for the asset pipeline.
    • lib/tasks/: Custom Rake tasks.
  • log/: Contains log files for different environments (e.g., development.log, production.log).
  • public/: Contains static files that are served directly by the web server (e.g., error pages like 404.html, 500.html, robots.txt).
  • storage/: (Used by Active Storage) For storing uploaded files locally if you’re not using a cloud service.
  • test/: Contains your application’s tests (e.g., unit tests, integration tests, system tests).
    • test/fixtures/: Sample data for your tests.
    • test/controllers/, test/models/, etc.
  • tmp/: For temporary files (e.g., cache, session data, PIDs).
  • vendor/: For third-party code not managed by Bundler (rarely used for JavaScript or CSS these days, as those are handled by app/javascript or asset pipeline and package managers like npm/yarn).

Key Files in the Root Directory:

  • Gemfile: Lists your application’s gem dependencies, managed by Bundler.
  • Gemfile.lock: Records the exact versions of all gems used, ensuring consistent environments.
  • Rakefile: Defines Rake tasks, although many common tasks are now available via bin/rails.
  • README.md: A Markdown file where you should describe your application, setup instructions, etc.
  • config.ru: A Rackup file used by Rack-based servers to start the application.

This standardized structure is a significant advantage of Rails, allowing developers to quickly understand project layouts and collaborate effectively.