Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An example rails 3.1 Engine
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Rails 3.1 Engine (baby_dove) Example

For a long time I've been wanting to incorporate a core application into another rails application. I've been working on a very deeply coded forum software called Ki-Rin and thought it would be wonderful if I could just move it entirely to an engine and let another application use it without restricting either application's core functionality.

Enter Rails 3 and Engines

With Rails 3, and especially 3.1 (edge rails), you now have the ability to create a fully functioning engine and add it to your application. However, with every new learning step, it's sometimes difficult to see the entire picture without having some code to use as a reference point. Therefore, I created a very simple example engine called baby_dove which will allow you to explore engines within Rails, and give you an idea of where to proceed.

Because I like living on the edge, I wanted to make an example that works with the latest rails version, 3.1.

What will you be accomplishing with this example?

You will be creating a Main Application and adding the baby_dove engine as a gem to your application. By adding the engine, you will be in effect sharing routes, controllers, models, views, libs, and rails dependencies globally.

Find a directory on your system where the mainapp and baby_dove will exist. They will be located in the same root directory, per below:

Directory Structure

some root folder
  • mainapp - Your main application

  • baby_dove - The rails 3 custom engine

The mainapp will be its own rails edge application. The baby_dove app will be a fully functioning rails engine. Do not create either directory yet. Follow the instructions below:

Preparing your Main App and Installing the Engine

From your root folder as per above..

  1. git clone

  2. rails new mainapp -d mysql

    create  README
    create  Rakefile
    create  .gitignore
    create  Gemfile
    create  app
    create  app/controllers/application_controller.rb
    create  app/helpers/application_helper.rb
    create  app/mailers
    create  app/models
    create  app/views/layouts/application.html.erb
  3. cd mainapp (your main application - not the engine).

  4. Edit config/database.yml from your main application and update as necessary.

  5. Edit your mainapp gemfile and add/substract the following, and then save it:

  • #comment out gem 'rails', '3.0.3' => #gem 'rails', '3.0.3'

  • add

    gem 'rails', :git => 'git://'

  • add

    gem 'arel', :git => 'git://'

  • add

    gem 'rack', :git => “git://”

  • add

    gem 'baby_dove', :path => “../baby_dove”

  • add

    gem 'coderay'

  • add

    gem 'jquery-rails'

Your mainapp gemfile should look like this:

source ''
gem 'mysql'
gem 'rails', :git => 'git://'
gem 'arel', :git => 'git://'
gem 'rack', :git => "git://"
gem 'baby_dove', :path => "../baby_dove"
gem 'coderay'
gem 'jquery-rails'

The first three gems we added allow you to use edge rails. The baby_dove gem is being required from a direct path. You can add it as a gem once you compile it, but by doing it this way, you can update the gem engine without having to rebuild it all of the time. It's like being on “edge engines”..

The coderay gem is being added because it's a part of our engine example, and jquery-rails is what we'll be using in our main app for javascript. Prototype, while okay as a basic javascript library, has been replaced by many developers who now enjoy using Jquery.

Cleaning up, bundling, and running

  1. Delete all javascript files in your main app minus application.js and rails.js.

  2. Delete the index.html file in your main apps public directory.

  3. cd mainapp (your main application not the engine).

  4. Type bundle install and hit enter.

  5. After bundling is finished type rails generate baby_dove and hit enter.

You should see something similar to

=> create  db/migrate/20101231052109_create_baby_dove_model_data.rb

What just occurred is that the baby_dove engine created a migration file in your main application that will handle the installation of any tables or data we want to add. You can find out more by looking into the engine source directories, especially under:


You can go inspect the migration that was installed from the engine to your mainapp.

  • –> Run rake db:create

  • –> Run rake db:migrate

  • –> Run rails server

Open up your localhost page and go to the following url:

localhost:3000/birds (or replace what your localhost:port is)

By default, I've set the routes.rb file in the engine to use the birds view as the default root.

You should see the view being added from birds. Play around with the birds controller and start inspecting every file in the engine and make sure to read the notes. You'll begin to understand just how easy it is to create an engine in rails 3.1.

Digging into the Code

  • baby_dove/app/controllers/baby_dove - contains our engine controller files

  • baby_dove/app/helpers/baby_dove - contains our engine helper files

  • baby_dove/app/models - contains our engine models

  • baby_dove/app/views/baby_dove - contains our engine views.

  • baby_dove/app/views/layouts - contains the baby_dove layout (yes you can use your own engine layout).

  • baby_dove/config/initializers - you can include any initializers you want to work with your engine here.

  • baby_dove/config/routes.rb - contains all of the engine routes.

  • baby_dove/lib/baby_dove.rb - houses our starting engine and includes requires.

  • baby_dove/lib/bird_feeder.rb - a simple module that I created to show how you can extend modules/classes/methods.

  • baby_dove/lib/baby_dove - houses our engine.rb file

  • baby_dove/lib/extensions - has an action_controller handle for custom methods

  • baby_dove/lib/generators - handles migrations

  • baby_dove/lib/nbproject - I created a netbeans project so if you use netbeans you can open this as a project in the IDE. Netbeans is not necessary to use this engine.

  • baby_dove/lib/public - With engines you now have the ability to serve static assets or incorporate them into your engine.

Things you may want to play with

  • Run rake routes from your main app so you can see how it's pulling in the engine routes as well as the application routes.

  • Open up all of the folders and files in the engine and read any notes I've added which will offer further explanations.

Important Notables

There are two very important decisions that you will ultimately decide on when constructing your engine and that is whether or not you will be namespacing it. If you completely namespace it, including the models, the model table names will be prefixed with engine_tablename. For instance, if baby_dove were completely namespaced on the models, the table for birds would be named baby_dove_birds instead of birds. Namespacing is fantastic on the surface, depending on how you utilize it, because you keep the engine completely separated from conflicts with the main application. However, there are some annoyances that bother me and I really think if you can be certain that your engine isn't going to create conflicts, then decide whether you really want to namespace it entirely, or whether you want to namespace certain aspects of it.

You can find more about namespacing mountable apps here:

Sources used to help create this engine

Contact me if you have any questions

I'm more than happy to answer questions as I find time to browse my email. If you have a question about engines or just want to chat, write to and send me some email. I look forward to hearing from you!

Something went wrong with that request. Please try again.