A Quick Study of the Rails Directory Structure
Ruby on Rails is a full fledged web framework written in Ruby. It is one of the most famous web frameworks and makes getting started with development so easy. Today I would like to explain the default files and folders generated by Rails. Let’s get started.
To create a new Rails app, all we have to do is run the following command:
rails new sample_app
The above command generates the directory structure that we’re discussing today. It might change if you are using an older version of Rails. This article is based on the latest Rails version which, as of this writing, is
4.2.4. You can find the version installed in your system by typing this in the console
rails version => Rails 4.2.4
The directory structure,
We will go through each directory, one by one, now.
This is the core directory of your entire app and most of the application-specific code will go into this directory. As you may know, Rails is an MVC framework, which means the application is separated into parts per its purpose in the Model, View, or Controller. These three sections goes inside this directory.
vendor) which we will look at in a bit.
All the images required for the application should go into this directory. The images here are available in views through nifty helpers like
image_tag("img_name.png") so that you don’t have to specify the relative or absolute path for images.
books_controller.rb, the JS functions for this controller’s views would be
application.js is the file where you reference the application specific JS files, which are unified and minified before sending it to the views.
This file is a manifest for the stylesheets in the application. Similar to
application.js, the referenced files are served up as a single stylesheet to the view.
This is where all the controller files go. Controllers are responsible for orchestrating the model and views. The naming convention for the file is the pluralized model name + “_controller”. For example, the controller for the
Book model is
books_controller.rb, which is called “snake case”. Also, the controller class will be CamelCase which is
The script to generate a controller is:
rails generate controller controller_name action1 action2
This is the main controller from which all other controllers inherit. The methods on
ApplicationController are available to other controllers as well. This controller inherits from the
ActionController::Base module, which has set of methods to work with in controllers.
Concerns are modules that can be used across controllers. This is helpful to DRY up your code by implementing reusable functionality inside the directory. The naming convention is
This is where all the helper functions for views reside. There are already a few pre-created helpers available, like the one we reference above (
image_tag) for referring to images in views. You can create your own functions in a controller specific helper file, which will be automatically created when you use Rails generators to create the controller. The naming convention is
This is the root helper. Similar to
application_controller.rb, functions written here will be available in all the helpers, by default, and in all the views.
mailers directory contains the mail (as in “email”) specific functions for the application. Mailers are similar to controllers and they will have their view files in
app/views/mailer_name/. To generate a mailer you can run the following command
rails generate mailer MailerName
The first time you generate a mailer,
application_mailer.rb is automatically created for you. This will inherit from the
ActionMailer::Base and sets the default
from address as well as the
layout for your mailer views. Subsequent mailers will inherit from
The naming convention is similar to controllers:
modelname_mailer.rb. You can read more about mailers here.
All model files live in the
app/models directory. Models act as object-relational mappers to the database tables that hold the data. The naming convention is simply
modelname.rb. The model name is, by convention, the singular form of the underlying table that represents the model in the database. So, the
Book model will be mapped on top of the
books table in the database. You can learn more about Rails models in here.
Model concerns are similar to Controller concerns, containing methods that might be used in multiple model files. This greatly helps with organizing the code.
The third part of the MVC architecture are the views. The files related to the views go into this directory. The files are a combination of HTML and Ruby (called Embedded Ruby or Erb) and are organized based on the controller to which they correspond. There is a view file for each controller action. For example, the
BooksController#index action would have it’s corresponding view as
This is another of Rails’ conventions, and can be broken. In other words, you can explicitly render any view manually.
This folder holds the layout for all your view files, which they inherit. Files created in here are available across all the view files.
You can create multiple layouts scoped to parts of application. For example, if we want to create a separate layout for administrative views vs user views, we can achieve it by creating a layout filed named after the controller name. For all
AdminController views, create a layout file called
admin.html.erb which will then act as the layout for the admin views, as well as any controller that inherits from
You can also create partial views here that might be used across controllers.
This will be default file created automatically, which will act as the layout for actions in
ApplicationController and any other contoller that inherits from
This directory contains Binstubs for the Rails application. Binstubs are nothing but wrappers to run the gem executables scoped to your application. This can be used in place of
bundle exec <command>. The default available Binstubs are
spring. Any of these binstubs can be executed by:
As the name suggests this contains all the application’s configuration files. The database connection and application behavior can be altered by the files inside this directory.
This contains the main configuration for the application, such as the timezone to use, language, and many other settings. The full list could be found here. Also, note the configurations specified here is for all environments (development, test, and production). Environment specific configurations will go into other files, which we’ll see below.
boot.rb, as you might imagine, “boots” up the Rails application. Rails apps keep gem dependencies in a file called
Gemfile in the root of the project. The
Gemfile contains all the dependencies required for the application to run.
boot.rb verifies that there is actually a
Gemfile present and will store the path to this file in an environment variable called
BUNDLE_GEMFILE for later use.
boot.rb also requires
'bundler/setup' which will fetch and build the gems mentioned in the
Gemfile using Bundler.
This file holds all the database configuration the application needs. Here, different configurations can be set for different environments.
This file requires
application.rb to initialize the Rails application.
This is where all the routes of the application are defined. There are different semantics for declaring the routes, examples of which can be found in this file.
Newly added in Rails 4.1, this gives you a place to store application secrets. The secrets defined here are available throughout the application using
Rails.application.secrets.<secret_name>. You can read more about
secrets.yml from the release notes.
As I mentioned above, this folder contains the environment-specific configuration files for the development, test, and production environments. Configurations in
application.rb are available in all environments, whereas you can separate out different configurations for the different environments by adding settings to the environment named files inside this directory. Default environment files available are,
test.rb, but you can add others, if needed.
This directory contains the list of files that need to be run during the Rails initialization process. Any
*.rb file you create here will run during the initialization automatically. For example, constants that you declare in here will then be available throughout your app. The initializer file is triggered from the call in
There are core initializers, which I’ll cover here, but you can add any Ruby file you like. In fact, many Rails gems require an initializer to complete the setup of that gem for your Rails app.
This contains configuration for the asset pipeline. It will have only one default configuration already defined,
Rails.application.config.assets.version, which is the version for your assets bundle. You can also specify configurations such as adding additional assets path or other items to precompile.
You can add backtrace_silencers and filters that might be applicable for your app here. Backtrace filters are nothing but filters that helps to refine the stacktrace when an error occurs. Silencers, on the other hand, let’s you silence all the stacktraces from specified gems.
There is not a whole lot of configuration happening here. It contains specifications for the app’s cookie serialization. You can read more about cookie handling in Rails from here.
You can add parameters here that might contain sensitive information and that you don’t want to display in your logs. By default, the “password” parameter will be filtered.
You can add/override the inflections (singularizations and pluralizations) for any language in here. You can learn more about the inflections API here.
Add MIME (Multi-purpose Internet Mail Extensions) configurations for your application here to handle different types of files you may want to use. The list of options available in Mime API can be found here.
This file contains the underlying session store to use in your app to store sessions. The default is
:cookie_store, meaning sessions are stored in browser cookies, but you can change it to one of four options. The options and more about the session store are available here.
As the name implies, it contains settings for wrapping your parameters. By default, all the parameters are wrapped into a nested hash so that it’s available without a root. You can override this or add your custom settings here.
This has the list of YAML file for each language that holds the keys and values to translate bits of the app. You can learn about internationalization (i18n) and the settings from here.
All the database related files go inside this folder. The configuration, schema, and migration files can be found here, along with any seed files.
This file is used to prefill, or “seed”, database with required records. You can use normal ActiveRecord methods for record insertion.
Gemfile is the place where all your app’s gem dependencies are declared. This file is mandatory, as it includes the Rails core gems, among other gems. You can learn all about Bundler and Gemfiles at the Bundler web site.
Gemfile.lock holds the gem dependency tree, including all versions, for the app. This file is generated by
bundle install on the above
Gemfile. It, in effect, locks your app dependencies to specific versions.
lib directory is where all the application specific libraries goes. Application specific libraries are re-usable generic code extracted from the application. Think of it as an application specific gem.
This file holds all the library assets, meaning those items (scripts, stylesheets, images) that are not application specific.
The application’s Rake tasks and other tasks can be put in this directory. Rake tasks mentioned here are required by the app’s
Rakefile, which we’ll see below.
This holds all the log files. Rails automatically creates files for each environment.
The public directory contains some of the common files for web applications. By default, HTML templates for HTTP errors, such as 404, 422 and 500, are generated along with a
favicon and a
robots.txt file. Files that are inside this directory are available in
Just above, I mentioned that Rake files created inside the
lib/tasks are available throughout the app via the Rake module. This is possible because of the Rakefile, which requires
application.rb and invokes
Rails.application.load_tasks. The call to
load_tasks loads all the
*.rake files from
The folder name says it all. This holds all the test files for the app. A subdirectory is created for each component’s test files.
This is the temporary directory for the app to hold files like caches. You don’t need to worry about this directory, since it’s fully managed by Rails itself. But there are few commands available if you want to take control of the directory, which can be found here
With that, we have come to the conclusion of this article. Understanding the directory and file structure of a Rails application can take you along way to grokking Rails. Please take time to go through the links I’ve referenced for customizations as they’ll help you on your journey to full-fledged Rails developer.