rails-engine-installers

Rails Engine Installers

Use this skill when the task is to design or review how a host app installs and configures a Rails engine — generating initializers, copying migrations, mounting routes, or exposing a single install command.

Core principle: Setup must be explicit, repeatable, and safe to rerun. Never modify the host app at boot time.

Installer Components

Component	Purpose	Key constraint
Generator	Creates initializer, route mount, or setup files	Must be idempotent — safe to rerun
Migrations	Copies engine migrations into host db/migrate	Host owns and runs them; never apply automatically
Initializer	Provides configuration defaults	Generated once, editable by host
Routes	Adds mount Engine, at: '/path'	Check for existing mount before injecting

HARD-GATE: Validation Workflow

WHEN building or reviewing an install generator:

1. GENERATE:  Run the generator against a clean host app
2. VERIFY:    Check output files exist in the correct host paths
3. RERUN:     Run the generator a second time
4. CONFIRM:   No duplicate files, routes, or initializer blocks inserted
5. DOCUMENT:  List what was generated vs. what the user must do manually
6. TEST:      Cover both single-run and rerun behavior in generator specs

DO NOT ship a generator without completing steps 3 and 4.

Constraints

Constraint	Do	Avoid
Boot-time mutation	Configure only in initializers	Modifying host files or state at load time from engine.rb or initializers
Idempotency	Guard with File.exist? or Thor's inject_into_file with a marker	Overwriting or inserting routes, initializers, or migrations without checking
Migrations	Copy to host db/migrate; host runs them	Applying migrations automatically
Manual steps	Document rollback steps and required env vars	Leaving install gaps undocumented
Docs accuracy	Match install docs to generator behavior	Docs that describe a different install path than the generator produces

Idempotency guards — check before creating or injecting:

def create_initializer
  return if File.exist?(File.join(destination_root, 'config/initializers/my_engine.rb'))
  create_file 'config/initializers/my_engine.rb', <<~RUBY
    MyEngine.configure do |config|
      config.user_class = "User"
    end
  RUBY
end

def mount_route
  # inject_into_file with force: false skips insertion if sentinel already present
  inject_into_file 'config/routes.rb',
    "\n  mount MyEngine::Engine, at: '/admin'\n",
    after: "Rails.application.routes.draw do",
    force: false
end

Minimal rerun spec (must always pass):

it 'does not duplicate the route mount on rerun' do
  2.times { run_generator }
  expect(File.read(file('config/routes.rb')).scan('mount MyEngine::Engine').size).to eq(1)
end

See EXAMPLES.md for a full generator class and complete spec suite, including migration copy helpers and multi-step install scenarios.

Generator Checklist

• Files created in correct host paths
• No duplicate inserts on rerun (validated manually and in specs)
• Sensible defaults that are easy to edit
• Clear output telling the user what remains manual
• Rollback steps documented
• Install docs match what the generator actually produces

Integration

Skill	When to chain
rails-engine-author	When designing the engine structure that installers will configure
rails-engine-docs	When documenting install steps or upgrade instructions
rails-engine-testing	When adding generator specs or dummy-app install coverage

Assets

• assets/README.md