In Rails 8.1, what is a Rails engine, and how does `rails plugin new --mountable` differ from `--full`?
answer
- an application is itself an engine
- no flag: a railtie gem
- --full blends into the host
- --mountable adds isolate_namespace
- test/dummy hosts the engine's tests
basics
~20 sA Rails engine is a gem whose Rails::Engine subclass adds app/ code, routes, migrations and config to a host app. --full blends into the host's namespace and routes; --mountable adds isolate_namespace and its own route set, mounted at a path.
solid answer
~40 sA `Rails::Engine` is a miniature Rails app packaged as a gem: its `app/` directories join the host's load paths, its `config/routes.rb`, locales, tasks and migrations are picked up, and `Rails::Application` itself inherits from `Rails::Engine`. `rails plugin new billing` with no flag only writes a gem with a `Rails::Railtie`. `--full` writes an engine without isolation: its `config/routes.rb` draws into `Rails.application.routes`, and its classes and helpers mix into the host's. `--mountable` adds `isolate_namespace Billing`, a `Billing::Engine.routes.draw` file, namespaced `ApplicationController`, `ApplicationRecord`, helper, job, mailer and layout stubs, and mounts the engine at `/billing` in the `test/dummy` app. The host then lists the gem in its Gemfile and adds `mount Billing::Engine, at: "/billing"` to its routes.
code
bash · 4 linesrails plugin new engines/billing --mountable
# lib/billing/engine.rb -> isolate_namespace Billing
# config/routes.rb -> Billing::Engine.routes.draw
# test/dummy/config/routes.rb -> mount Billing::Engine => "/billing"go deeper
Recall the three outcomes of rails plugin new: railtie gem, full engine, mountable engine. Know the two host steps: a Gemfile entry and a mount line.
Explain what --mountable adds over --full: isolate_namespace, the engine's own route set, namespaced base classes and a mounted dummy app. Say where each flavour's routes end up.
Choose the flavour from the coupling you want: full for shared concerns and models, mountable for a feature with its own URLs and names. Mention the dummy app as the engine's test host.
Frame engines as an in-process packaging tool: they share the host's process, database and lockfile, so they organise code without creating a deployable boundary.
## What an engine is A **Rails engine** is a subclass of `Rails::Engine` shipped inside a gem (or a folder the host loads with `gem "billing", path: "engines/billing"`). Rails treats it as a smaller application that lives inside the real one: - its `app/models`, `app/controllers`, `app/views`, `app/helpers` and the other `app/*` folders become part of the host's autoloaded and eager-loaded code; - its `config/routes.rb`, `config/locales/**`, `config/initializers` and `lib/tasks` are loaded; - its `db/migrate` folder can be copied into the host with an install task; - it has its own `config` object and can declare initializers, because every engine is also a `Rails::Railtie`. The relationship runs the other way too: `Rails::Application` inherits from `Rails::Engine`. Your app is the biggest engine in the process, which is why an engine's folder layout looks exactly like an app's. ## What `rails plugin new` writes The plugin generator (`rails plugin new NAME`) has two engine switches, and the third case is easy to forget. | Command | Main class written | `config/routes.rb` | Namespacing | |---|---|---|---| | `rails plugin new billing` | `Billing::Railtie < ::Rails::Railtie` | none | none: it is a plain gem with a railtie | | `rails plugin new billing --full` | `Billing::Engine < ::Rails::Engine` | `Rails.application.routes.draw do` | none: classes, helpers and routes blend into the host | | `rails plugin new billing --mountable` | `Billing::Engine` with `isolate_namespace Billing` | `Billing::Engine.routes.draw do` | everything under `Billing::`, tables prefixed `billing_` | Both engine flavours also get `app/models/concerns`, `app/controllers/concerns`, a `test/` tree and a **dummy application** under `test/dummy` (the `--dummy-path` option moves it). The dummy app is a generated Rails app that requires your engine so its controllers, routes and models can be tested in a real host. `--mountable` adds, on top of `--full`: 1. `isolate_namespace Billing` in `lib/billing/engine.rb`; 2. a route file drawn on the engine's own route set, `Billing::Engine.routes.draw`; 3. namespaced base classes: `Billing::ApplicationController`, `Billing::ApplicationRecord`, `Billing::ApplicationJob`, `Billing::ApplicationMailer` and `Billing::ApplicationHelper`; 4. a layout at `app/views/layouts/billing/application.html.erb` and a stylesheet at `app/assets/stylesheets/billing/application.css`; 5. `mount Billing::Engine => "/billing"` in `test/dummy/config/routes.rb`. In Rails 8.1 the generator writes no Sprockets `manifest.js`; the older list in the engines guide that mentions one predates Propshaft. `--api` gives either flavour a smaller stack (`ActionController::API`, no views or helpers in a mountable engine). ## Working inside the engine The engine gets its own `bin/rails`. It sets `ENGINE_ROOT` and `ENGINE_PATH` to the engine and `APP_PATH` to the dummy app's `config/application`, so commands run from the engine's root behave like commands in a small app: - `bin/rails generate model invoice amount_cents:integer` writes `Billing::Invoice` and a migration into the engine itself, not into any host; - `bin/rails server` boots the dummy app with the engine loaded, which is handy for clicking through engine screens; - the engine's `Gemfile` contains `gemspec`, so dependencies declared in the `.gemspec` are installed for development; - the `.gemspec` lists `app`, `config`, `db` and `lib` as the gem's files, which is what a host receives when the engine is published as a gem. ## Full or mountable: which one A **full engine** suits code that should feel like part of the host: shared models, a set of concerns, or extra routes that belong in the app's own URL space. Its routes are drawn straight into the host route set, so nothing is mounted, and its helpers are included in host controllers like any helper in `app/helpers`. A **mountable engine** suits a self-contained feature with its own URLs: an admin area, a billing section, a forum. It gets its own route table, its own helpers and its own table prefix, so names such as `InvoicesController`, `invoices_path` or an `invoices` table cannot collide with the host's. ## Wiring it into the host Two steps make a mountable engine reachable: 1. Add the gem: `gem "billing", path: "engines/billing"` (running the generator inside an app's directory appends this entry for you unless `--skip-gemfile-entry` is passed). 2. Mount it in `config/routes.rb`: `mount Billing::Engine, at: "/billing"`. After that, requests under `/billing` are dispatched to the engine's route set, and the host can link into it with the `billing` route proxy. A full engine needs only step 1, because its routes are already in the host's table. ## Common misconceptions - **"A plugin is always an engine."** Without `--full` or `--mountable` the generator writes a railtie gem with no `app/` tree. - **"Mountable means a separate process."** The engine runs inside the host's process, database connection and Gemfile.lock. - **"`--full` engines must be mounted."** Their routes already live in `Rails.application.routes`.
- Why do engines ship a test/dummy application?An engine is not runnable on its own: controllers need a router, a database and a Rails process. The generator writes a minimal Rails app under `test/dummy` that loads the engine (and, for `--mountable`, mounts it at `/billing`), so the engine's tests boot a real host without depending on any production app.
- Can a full engine later become mountable?Yes, but it is a rename, not a flag: add `isolate_namespace Billing`, move the routes onto `Billing::Engine.routes.draw`, nest classes under `Billing::`, and expect the default table names to gain the `billing_` prefix, so existing tables need `self.table_name` or a rename migration.
- rails plugin new without flags already generates a full engine
- A mountable engine runs as its own process or service
- A --full engine must be mounted with mount before its routes work
- Engines are a separate concept from Rails::Application
- --mountable writes a Sprockets manifest.js in a new 8.1 engine
Assumes Rails 8.1: the plugin generator writes a Propshaft-era engine with application.css and no Sprockets manifest.js, unlike older guide text.