rails-pro

Overview

Rails is the original convention-over-configuration framework: follow its opinions about naming, directories, and REST, and enormous amounts of behavior (routing, ORM, migrations, mailers, jobs, caching) come free. Deviate silently and you fight the framework at every step. This skill covers idiomatic Rails — the parts that make teams fast (ActiveRecord, migrations, Hotwire) and the parts that bite (N+1s, callback spaghetti, deploy config) — plus modern Rails with import maps, Turbo, and Stimulus.

When to use

• Building a full-stack web app the Rails way (monolith-first).
• Fixing N+1 queries, slow pages, or callback-heavy models.
• Structuring jobs, mailers, and service objects in a growing app.
• Using Hotwire (Turbo + Stimulus) instead of a JS SPA.
• Deploying Rails to production (assets, DB, workers, caching).
• Upgrading Rails across major versions.
• Adding an API to an existing Rails monolith.

Core concepts

• Convention over configuration. File names, class names, table names, and routes map to each other (UsersController → app/controllers/users_controller.rb → users table). Learn the conventions once and the framework disappears.
• ActiveRecord is the heart. Models map to tables; associations (has_many, belongs_to) generate queries. Eager load with .includes to kill N+1s; use scopes for composable query logic; keep SQL fragments minimal and parameterized.
• Migrations with discipline. Each migration should be small, reversible (change), and safe on large tables — add columns without defaults/backfill separately, add indexes CONCURRENTLY (via algorithm: :concurrently on Postgres), never rewrite history that's deployed.
• Callbacks are a code smell at scale. before_save/after_commit chains create invisible coupling. Prefer explicit service objects or form objects for multi-model operations; reserve callbacks for true model invariants.
• Hotwire over SPA. Turbo Drive/Frames/Streams plus Stimulus controllers deliver SPA-like interactivity with server-rendered HTML. Reach for it before adding React — most CRUD apps don't need a JS framework.
• Background jobs via ActiveJob. Sidekiq (Redis-backed) is the standard adapter. Jobs must be idempotent and retry-safe; pass IDs, not objects; keep payloads small.
• The asset pipeline, modern. Import maps + Sprockets or Propshaft for JS without a bundler; use a bundler (esbuild/vite via jsbundling-rails) only when you need npm-heavy frontend code.
• Strong Parameters. params.require(:user).permit(:name, :email) — the mass-assignment protection at the controller boundary. Never skip it; it's the difference between a form and a privilege-escalation vector.
• Caching. Russian-doll fragment caching, low-level Rails.cache.fetch, HTTP caching with ETags — Rails' caching is excellent when keys are versioned on the underlying records (cache_key_with_version).
• Zeitwerk autoloading. Constants map to file paths; no more require spaghetti. Name files correctly and autoloading disappears as a concern — misname them and you get uninitialized-constant mysteries.
• ActiveStorage. Uploads backed by local disk/S3/GCS with variants for image processing; use direct uploads so large files bypass the app server.
• Action Mailbox/Text. Inbound email/SMS routed into the app as first-class objects — handy for support inboxes and reply-by-email features without extra services.

Practical workflow

1. Generate with intent. rails new shop --database=postgresql --css=tailwind; keep the monolith until a real boundary demands extraction.

2. Model the domain. Resources first (resources :orders), models with validations and associations, scopes for query logic, service objects (app/services/) for multi-step operations.

   class Order < ApplicationRecord
     belongs_to :customer
     has_many :line_items, dependent: :destroy
     scope :recent, -> { order(created_at: :desc) }
     scope :paid, -> { where(status: "paid") }
   end
   

3. Kill N+1s early. Install the bullet gem in development — it shouts when you eager-load wrong. Review with rack-mini-profiler on slow pages.

4. Add interactivity with Hotwire. Turbo Frames for partial updates, Turbo Streams for realtime via ActionCable, Stimulus controllers for client-side behavior. Write system tests for the flows.

   • Keep Stimulus controllers small and single-purpose; reach for Turbo Streams before custom JS.

5. Jobs and mailers. ActiveJob + Sidekiq; mailers with parameterized previews; all async work idempotent with exponential backoff.

   class InvoiceJob < ApplicationJob
     queue_as :billing
     retry_on ActiveRecord::Deadlocked, attempts: 5
     def perform(invoice_id)
       Invoice.find(invoice_id).generate_pdf!
     end
   end
   

6. Test the pyramid. Model/unit tests fast and many; request specs for API behavior; system tests (Cuprite/Selenium) sparingly for critical flows — they're slow, so choose the flows that matter.

7. Cache deliberately. Fragment caching with versioned keys, stale?/fresh_when for HTTP caching, and low-level caching for expensive computations — with explicit expiration strategies.

8. Ship it. Compile assets at build time, run migrations in a release phase (not in web boot), provision Redis for cache/jobs/Cable, set RAILS_MASTER_KEY via secrets management, and enable structured logging.

   # Turbo Stream broadcast from a model — realtime without custom JS
   class Message < ApplicationRecord
     after_create_commit -> { broadcast_append_to "room_#{room_id}", target: "messages" }
   end
   

Common pitfalls

• N+1 queries in views and serializers — Bullet in dev, includes in code, query-count assertions in tests.
• Callback hell — chains of after_save that trigger other saves; extract to service objects with explicit sequencing.
• Unsafe migrations on big tables — locking ALTER TABLE during deploys; use concurrent index creation and multi-step column changes.
• Passing ActiveRecord objects to jobs — serialization breaks and stale data; pass IDs and re-fetch.
• Ignoring the asset pipeline — shipping uncompiled assets or massive JS bundles; audit with build output sizes.
• Secrets in the repo — credentials.yml.enc + master key via env/secret store; never commit the key.
• No database timeouts — set statement_timeout and pool sizes; a hung query should fail, not cascade.
• Skipping Strong Parameters — mass-assignment vulnerabilities; permit explicitly at every controller boundary.
• ActionCable without Redis in production — the async adapter doesn't work across processes; configure the Redis adapter.
• Forgetting dependent: on associations — orphaned rows accumulating; decide destroy/nullify/restrict explicitly per association.
• Turbo + custom JS conflicts — event listeners vanish on Turbo navigation; hook turbo:load or move behavior into Stimulus controllers.
• Abusing default_scope — surprising query behavior in every context; prefer explicit named scopes at call sites.
• CookieStore overflow — sessions over 4KB break; switch the session store to cache or DB when storing more than a user id.