Rails 3.1: Engine vs. Mountable App

Question

Can someone help me understand the differences between a Rails Engine and a Mountable app? In Rails 3.1, you can create either one with the \"rails new plugin _

Answer 1

Both options will generate an engine. The difference is that --mountable will create the engine in an isolated namespace, whereas --full will create an engine that shares the namespace of the main app.

The differences will be manifested in 3 ways:

1) The engine class file will call isolate_namespace:

lib/my_full_engine/engine.rb:

module MyFullEngine
  class Engine < Rails::Engine
  end
end

lib/my_mountable_engine/engine.rb:

module MyMountableEngine
  class Engine < Rails::Engine
    isolate_namespace MyMountableEngine # --mountable option inserted this line
  end
end

2) The engine's config/routes.rb file will be namespaced:

Full engine:

Rails.application.routes.draw do
end

Mounted engine:

MyMountableEngine::Engine.routes.draw do
end

3) The file structure for controllers, helpers, views, and assets will be namespaced:

create app/controllers/my_mountable_engine/application_controller.rb
create app/helpers/my_mountable_engine/application_helper.rb
create app/mailers create app/models
create app/views/layouts/my_mountable_engine/application.html.erb
create app/assets/images/my_mountable_engine
create app/assets/stylesheets/my_mountable_engine/application.css
create app/assets/javascripts/my_mountable_engine/application.js
create config/routes.rb create lib/my_mountable_engine.rb
create lib/tasks/my_mountable_engine.rake
create lib/my_mountable_engine/version.rb
create lib/my_mountable_engine/engine.rb

---

Explanation

The use case for the --full option seems to be very limited. Personally I can't think of any good reason why you'd want to separate your code into an engine without isolating the namespace as well- It would essentially just give you two tightly coupled applications sharing identical file structures and all the conflicts and code leakage that entails.

Every piece of documentation I've seen demonstrates the --mountable option, and indeed the current edge guide strongly encourages you to include isolate namespace- which is the same as saying use --mountable over --full.

Finally there's terminology confusion: Unfortunately rails plugin -h shows the following descriptions:

[--full] # Generate a rails engine with bundled Rails application for testing
[--mountable] # Generate mountable isolated application

This gives the impression that you use --full to create an "engine" and --mountable to create something else called a "mountable application", when in fact they're both engines - one namespaced and one not. That's bound to lead to confusion as users looking to create an engine will likely assume that --full is the more relevant option.

Conclusion

• rails plugin new something --full = Engine in your app's namespace. (Why would you?)
• rails plugin new something --mountable = Engine with it's own namespace. (Awesome)

---

References

• http://edgeguides.rubyonrails.org/engines.html
• http://api.rubyonrails.org/classes/Rails/Engine.html
• http://railscasts.com/episodes/277-mountable-engines
• https://github.com/rails/rails/pull/6499