Engines, generators and application templates

Kaksha’s fees team and its admissions team ship from one repository, and the feature-flag screen both of them wanted grew into four files nobody owned. One command, rails plugin new feature_flags --mountable, gives that screen its own routes file, its own feature_flags_ table prefix and its own test suite without leaving the repository.

Rails has three tools for work of that kind, and they answer different questions. Engines package a slice of an application so that another application can mount it. Generators write the files a team keeps typing by hand. Application templates set a new application up the way the team agreed. By the end you can build one of each and say which boundary a slice of code deserves.

An engine is a Rails app that lives inside another one

One command writes the skeleton. rails plugin new feature_flags --mountable --skip-git --skip-javascript leaves a gemspec, lib/feature_flags/engine.rb, a routes file drawn on the engine rather than on Rails.application, an app/ tree under feature_flags/, and a complete host application in test/dummy. The engine class is five lines, and the line that decides the rest is isolate_namespaceisolate_namespace: The engine call that looks up the engine's classes inside its module, prefixes its table names and keeps its route helpers in a route set of their own..

That one call turns an engineengine: A Rails application packaged as a gem, with its own app folder, routes, migrations and tests, loaded inside a host application. into something you can hand to another team. Rails keeps its models, controllers and helpers inside the FeatureFlags module, prefixes its tables with feature_flags_, and keeps its route helpers in a set of their own. Without it both apps’ FlagsController classes are one constant, and both apps’ flags tables are one table.

The run below generates the engine, fills the gemspec’s eight TODO placeholders from this lesson’s copy, generates a model, and asks Rails what it made of that:

require_relative "session"

# What rails plugin new writes, and what isolate_namespace then decides for you.
Session.run(<<~SH, masks: [[/\b20\d{12}/, "…"]])
  # An engine is a small Rails app in a gem. One command writes the whole skeleton:
  rails plugin new ../feature_flags --mountable --skip-git --skip-javascript --skip-bundle 2>&1 | grep -E "engine.rb|config/routes.rb|gemspec|application_controller|dummy"
  cd ../feature_flags
  rm -rf .github
  # The one line that keeps the engine's names out of the app's:
  cat lib/feature_flags/engine.rb
  # Its routes are drawn on the engine, never on Rails.application:
  cat config/routes.rb
  # The gemspec arrives with placeholders; nothing installs the engine until they are filled:
  grep -c TODO feature_flags.gemspec
  # This lesson's filled gemspec, a route and a controller go in:
  cp -R ../lab/engine/. .
  bundle install --local 2>&1 | tail -1
  # A model, generated inside the engine as you would inside an app:
  bin/rails generate model Flag name:string enabled:boolean
  grep -A4 create_table db/migrate/*_create_feature_flags_flags.rb
  # The engine's own routes, and the app's single line that leads to them:
  bin/rails routes -g flags
SH

# An engine is a small Rails app in a gem. One command writes the whole skeleton:
$ rails plugin new ../feature_flags --mountable --skip-git --skip-javascript --skip-bundle 2>&1 | grep -E "engine.rb|config/routes.rb|gemspec|application_controller|dummy"
      create  feature_flags.gemspec
      create  app/controllers/feature_flags/application_controller.rb
      create  config/routes.rb
      create  lib/feature_flags/engine.rb
  vendor_app  test/dummy
$ cd ../feature_flags
$ rm -rf .github
# The one line that keeps the engine's names out of the app's:
$ cat lib/feature_flags/engine.rb
module FeatureFlags
  class Engine < ::Rails::Engine
    isolate_namespace FeatureFlags
  end
end
# Its routes are drawn on the engine, never on Rails.application:
$ cat config/routes.rb
FeatureFlags::Engine.routes.draw do
end
# The gemspec arrives with placeholders; nothing installs the engine until they are filled:
$ grep -c TODO feature_flags.gemspec
8
# This lesson's filled gemspec, a route and a controller go in:
$ cp -R ../lab/engine/. .
$ bundle install --local 2>&1 | tail -1
Use `bundle info [gemname]` to see where a bundled gem is installed.
# A model, generated inside the engine as you would inside an app:
$ bin/rails generate model Flag name:string enabled:boolean
      invoke  active_record
      create    db/migrate/…_create_feature_flags_flags.rb
      create    app/models/feature_flags/flag.rb
      invoke    test_unit
      create      test/models/feature_flags/flag_test.rb
      create      test/fixtures/feature_flags/flags.yml
$ grep -A4 create_table db/migrate/*_create_feature_flags_flags.rb
    create_table :feature_flags_flags do |t|
      t.string :name
      t.boolean :enabled

      t.timestamps
# The engine's own routes, and the app's single line that leads to them:
$ bin/rails routes -g flags
Routes for application:
       Prefix Verb URI Pattern    Controller#Action
feature_flags      /feature_flags FeatureFlags::Engine

Routes for FeatureFlags::Engine:
Prefix Verb URI Pattern          Controller#Action
 flags GET  /flags(.:format)     feature_flags/flags#index
  flag GET  /flags/:id(.:format) feature_flags/flags#show
  root GET  /                    feature_flags/flags#index

The generated migrationmigration: A Ruby file in db/migrate/ that changes the database schema one step, named with the time it was made so that every database runs the steps in the same order. More in “The Rails command line, console and generators” says create_table :feature_flags_flags, and bin/rails routes -g flags prints two tables: the dummy app’s one line for the whole engine, and the engine’s own routes under controllers named feature_flags/flags. Step through where such a request goes:

Three tools, and the moment each one fits

Each of the three belongs to a different moment: code a second application will run, the fifth time a team writes the same three files by hand, and the next new application.

Six more pieces come up again and again in this work. --mountable gives a mountable enginemountable engine: An engine generated with --mountable: it isolates its namespace and draws its own routes, so a host application mounts it at a path of the host's choosing. its own namespace and routes, while --full leaves it sharing the host app’s. A dummy appdummy app: The small host application under an engine's test/dummy that the engine's own test suite boots, so the engine can be tested without any other application. in test/dummy is the host application an engine’s suite boots. bin/rails feature_flags:install:migrations copies an engine’s migrations into the host app with new time stamps. A custom generatorcustom generator: A generator a team writes itself, usually a subclass of Rails::Generators::NamedBase, so that bin/rails generate writes the files the team's own conventions need. subclassing Rails::Generators::NamedBase turns one name into files written from .tt templates. An application templateapplication template: A Ruby script of Thor actions that sets an application up, applied by rails new -m or by the app:template task on an application that already exists. is a script of Thor actions that rails new -m or bin/rails app:template applies. A packwerkpackwerk: A tool that reads the constants each file of a Rails application references and reports every reference that crosses a package boundary the packages did not declare. package is a folder whose package.yml names the packages it may reference.

Engines and application templates are decisions a team makes once and lives with; generators are the ones it runs every week. Using the generators Rails already ships is covered in the command line and generators lesson.

Choosing between an engine, a package and a separate app

A boundary costs something, and these three cost different things. Answer the figure’s questions about the slice you want to separate, and watch options drop out with their reason.

In short: an engine when a second application will mount the code, a package boundarypackage boundary: A rule about which parts of one application may reference which others, written down in configuration so a command can report a reference that crosses it. when one application needs its dependencies kept honest, and a separate application when the slice must be released on its own. The architecture argument sits in organising business logic.

A mountable engine end to end: model, routes, migrations and tests Pro: opens with a Pro, Premium or Ultimate pass

Custom generators and an application template a team can run twice Pro: opens with a Pro, Premium or Ultimate pass

Package boundaries with packwerk, and the violation it reports Pro: opens with a Pro, Premium or Ultimate pass

Practise on the runs above

Copy a session from the examples folder and change it, predicting each result first.

1. In engine_session.rb, drop isolate_namespace FeatureFlags before the model is generated, and predict the table the migration creates.
2. In mount_session.rb, mount the engine at: "/switches" and predict which of the three tests fail.
3. In packwerk_session.rb, make enrolment.rb reference Invoice as well, and predict how many offences the last check reports.

Interview questions

What does isolate_namespace change in an engine, and what breaks without it?

It moves three things into the engine’s module. Models, controllers and helpers live inside FeatureFlags, so the engine’s FlagsController can never collide with a host app’s class of that name. Table names gain a feature_flags_ prefix, so the engine’s Flag reads feature_flags_flags. Route helpers move to the engine’s own set, reached from the app through the mount’s proxy, feature_flags.flags_path. Without the call the engine shares the host app’s namespace, and the first definition Zeitwerk loads wins, which surfaces as a controller answering with somebody else’s action or a migration failing because the table exists.

Each question below starts from a decision, so settle on yours and write the reason down first.

Key takeaways

• An engine is a Rails application packaged as a gem, and isolate_namespace keeps its constants, tables and route helpers out of the host app’s.
• The host app names one path for the whole engine, and every route below that path is the engine’s business.
• A generator is for files a team writes repeatedly; an application template is for the defaults of the next new application.
• Package boundaries suit a slice that stays in one application, where a build command reports any reference across them.
• Which boundary fits follows from three questions: reuse by a second application, an independent release, and who maintains it.