Rails engines in large apps

Rails engines in
large apps
Created by /Enrico Teotti @agenteo

Start off with a small
application

and the app complexity will
grow over time

Start off with a big complex
application

ignoring complexity will hurt
you

In Ruby on Rails that is:

too many responsibilities in
active record models

helpers modules doing a
gazillion things

These poor decisions are sometime justified as:
"This is the Rails way!"
"Those are the Rails
conventions!"
"This is what a Rails developer
expect to see!"

Rails gives conventions that fit small application domains but doesn't
have any for larger problems

How can Ruby on Rails engines
help?

Engines can drop in functionality in your Rails monolithic app
Devise
Kaminari

But they can do more that that
"Rails::Engine allows you to wrap a specific Rails application or subset of
functionality and share it with other applications or within a larger
packaged application. Since Rails 3.0, every Rails::Application is just an
engine, which allows for simple feature and application sharing."
Rails API

we will create very specific engine only used in this app

Domain Model
This is a domain model taken from Evan's book DDD
It is a simplified version of a real live problem

use Engines as building bricks
of the application!

First, create an integration test
in the main app
spec/features/ship_cargo_spec.rb
require 'spec_helper'
feature 'As a staff member I want to ship a cargo' do
scenario %{
Given I am on the cargo shipping page
When I fill in a customer
And I fill in a origin and destination
Then I want to see an itinerary } do
visit '/ship_cargo'
end
end

rspec
F
Failures:
1) As a staff member I want to ship a cargo
Then I want to see an itinerary
Failure/Error: visit '/ship_cargo'
ActionController::RoutingError:
No route matches [GET] "/ship_cargo"
# ./spec/features/ship_cargo_spec.rb:10:in `block (2 levels) in <top (required)="">'
Finished in 0.00523 seconds
1 example, 1 failure
</top>

Create an engine
rails plugin new cargo_shipping --mountable -T --dummy-path=spec/dummy

You can create a nested folder
structure
If you want to be more formal about the separation of
responsibilities between the engines
The engine name will match ubiquitous language you share with
stakeholders
engines/
├── application_layer
├── domain_layer
│ ├── billing
│ ├── customer
│ └── shipping
└── presentation_layer
└── cargo_shipping

Main app Gemfile
gem 'cargo_shipping', path: 'engines/presentation_layer/cargo_shipping'

Cargo Shipping Engine
structure
engines/presentation_layer/cargo_shipping/
├── Gemfile
├── Gemfile.lock
├── MIT-LICENSE
├── README.rdoc
├── Rakefile
├── app
│ ├── assets
│ ├── controllers
│ ├── helpers
│ ├── mailers
│ └── views
├── cargo_shipping.gemspec
├── config
│ └── routes.rb
├── lib
│ ├── cargo_shipping
│ ├── cargo_shipping.rb
│ └── tasks
└── spec
└── dummy

CargoShipping Engine routes
engines/presentation_layer/cargo_shipping/config/routes.rb
module PresentationLayer
CargoShipping::Engine.routes.draw do
get 'ship_cargo', to: 'ship_cargo#new'
end
end

CargoShipping Engine
controller
engines/presentation_layer/cargo_shipping/app/controllers/cargo_shipping/ship_cargo_controller.rb
module CargoShipping
class ShipCargoController < ActionController::Base
def new
end
end
end

Run the test again!
F
Failures:
ActionController::RoutingError:
No route matches [GET] "/ship_cargo"
</top>

We need to change the main
app routes!
config/routes.rb
Maersk::Application.routes.draw do
mount CargoShipping::Engine, at: "/"
end

rspec
.
1 example, 0 failures

CargoShipping Engine
engines/presentation_layer/cargo_shipping/app/controllers/cargo_shipping/ship_cargo_controller.rb
module CargoShipping
class ShipCargoController < ActionController::Base
def new
@customers = Customers::CustomerRepository.all
end
end
end

rspec
F
Failures:
NameError:
uninitialized constant CargoShipping::ShipCargoController::Customers
# ./engines/presentation_layer/cargo_shipping/app/controllers/cargo_shipping/ship_cargo_controller.r
</top>

Create a domain layer engine
rails plugin new customers --mountable -T --dummy-path=spec/dummy

Main app Gemfile
gem 'cargo_shipping', path: 'engines/presentation_layer/cargo_shipping'
gem 'customers', path: 'engines/domain_layer/customers'

Generating models in
Customers Engine
engines/domain_layer/customers/app/models/customers/customer_repository.rb
rails generate model CustomerRepository email name
invoke active_record
create db/migrate/20130921154844_create_customers_customer_repositories.rb
create app/models/customers/customer_repository.rb
invoke rspec
create spec/models/customers/customer_repository_spec.rb

Mailing list:
https://groups.google.com/forum/?hl=en#!forum/components-in-rails
References:
Wrangling Large Rails Codebases
Architecting your Rails app for success!
http://pivotallabs.com/leave-your-migrations-in-your-rails-
engines/
http://pivotallabs.com/experience-report-engine-usage-that-
didn-t-work/

THE END
Enrico Teotti / @agenteo / teotti.com

Rails engines in large apps

Recommended

More Related Content

What's hot (20)

Similar to Rails engines in large apps (20)

More from Enrico Teotti (12)

Recently uploaded (20)

Rails engines in large apps