That’s the gap EagerEye tries to close. It’s a static analyzer for Rails — no DB, no Rails boot, no runtime hooks. It parses your Ruby files into an AST and looks for patterns that turn into N+1 queries at runtime. In this post I’ll walk through the design decisions behind it, show what it catches that Bullet can’t, share the real-world numbers from running it on production codebases, and explain how to wire it into CI in five lines of YAML.
Bullet is a runtime tool. It hooks into ActiveRecord’s association loading mechanism and notices when you call an association that wasn’t preloaded. This is brilliant when it works, but it has a fundamental constraint: the code path has to actually run.
Most teams I’ve worked with have decent test coverage for their happy paths but limited coverage for everything else: admin actions, error branches, rarely-hit feature flags, background jobs that only fire on specific events. Bullet sees nothing in any of those code paths. Worse, if the test happens to use fewer records than would trigger an N+1 in production (create(:user, :with_posts) in a fixture vs. 10,000 users in prod), you can pass tests with hidden N+1s.
Static analysis solves a different problem. It reads every line of code, regardless of whether it ever executes. It finds patterns. It doesn’t need fixtures, doesn’t need a DB, doesn’t need Redis. It runs in milliseconds per file, not minutes.
The trade-off is that it can’t verify anything. A heuristic that matches posts.each { |p| p.author } might be flagging a real N+1 — or it might be flagging code where posts was already preloaded somewhere static analysis can’t see. The only honest path forward is to design the tool around minimizing false positives, even if it costs some false negatives.
That principle — a warning you can trust is more useful than a warning you have to investigate — is what shaped the entire design.
EagerEye ships 11 detectors. Some overlap with Bullet (the simple loop case), most don’t.
posts.each do |post|
post.author.name # query per post
post.comments.count # another query per post
end
EagerEye flags both lines and suggests .includes(:author, :comments). So does Bullet, if this code is exercised by a test that loops over enough posts. But if the loop is in an admin export controller that nobody tests, Bullet stays silent. EagerEye doesn’t care — it sees the loop and the association access regardless.
class User < ApplicationRecord
has_many :teams
def supports?(team_name)
teams.where(name: team_name).exists?
end
end
@users.each { |user| user.supports?("Lakers") }
This is the example I opened the previous post with. Bullet can’t catch it because teams.where(...) bypasses the association loading hook. EagerEye scans every model file once, builds a map of which methods contain query calls, then flags any iteration that calls one of those methods on the iteration variable.
class PostSerializer < Blueprinter::Base
field :author_name { |post| post.author.name }
end
# Controller — no preload
render json: PostSerializer.render(@posts)
Serializers are an N+1 graveyard. They run once per record, often access nested associations, and the controller doesn’t always know which fields the serializer touches. EagerEye scans Blueprinter, ActiveModel::Serializer, and Alba blocks for nested association access and suggests preloading at the source.
.count vs .size trap@users = User.includes(:posts)
@users.each { |user| user.posts.count } # SELECT COUNT(*) per user, even though posts are loaded
.count always queries. .size uses the loaded array if available. Bullet doesn’t catch this because the association is preloaded — you’re just not using the preload. EagerEye flags every .count on an association inside an iteration block.
class Order < ApplicationRecord
after_create :notify_subscribers
def notify_subscribers
customer.followers.each do |follower|
follower.notifications.create!(...) # N inserts + N queries per save
end
end
end
Order.import(big_array) triggers the callback for every record. Per record, you get an iteration that fires queries. Bullet usually doesn’t run during background jobs and doesn’t track create! patterns. EagerEye specifically scans after_* / before_* / around_* callback bodies for iteration-driven queries.
MissingCounterCache, PluckToArray, DelegationNPlusOne, DecoratorNPlusOne, ScopeChainNPlusOne, ValidationNPlusOne — each targets a pattern from the previous post. The full list with code samples lives in the README.
The naive approach to “find loops with association calls” is a regex like /each.*\.(\w+)\.\w+/. This breaks on the first multi-line block, misses Hash literals, and confuses string interpolation with method calls. AST parsing means we work with the actual structure Ruby sees: :block nodes contain a :send (the iteration call), an :args list, and a body of statements. Walking that tree is annoying but reliable.
The implementation uses whitequark/parser, the same parser RuboCop uses. Ruby 3.1+ syntax is supported.
One of the gnarlier bugs in early versions was this:
def index
invoices = Invoice.includes(:customer, :merchant).where(active: true)
@data = invoices.map { |i| [i.customer.name, i.merchant.name] }
end
def some_other_action
invoices = Invoice.where(id: params[:ids]) # no includes here
invoices.update_all(status: 'archived')
end
The first version of EagerEye tracked invoices globally across the file. So when it processed def some_other_action, the invoices variable assignment overwrote the preload information from def index, and the iteration in index started getting flagged for N+1 even though :customer and :merchant were preloaded.
The fix was treating each :def body as an independent scope: variables inherit a snapshot from the enclosing scope, but writes inside a method don’t leak out. This is closer to how Ruby actually works and eliminated about 19 false positives on the iwallet codebase alone.
A common Rails pattern is to extract serialization into a helper:
def index
@users = User.includes(:profile, :organization)
@data = prepare_data(@users)
end
private
def prepare_data(users)
users.map { |u| [u.profile.bio, u.organization.name] }
end
The iteration is in prepare_data. Static analysis can see that users is a method parameter — but without inter-procedural analysis, it can’t know that the only caller (index) preloads :profile and :organization.
EagerEye does a two-pass analysis per class: pass 1 collects every self-call between sibling methods along with the caller’s variable state at the call site; pass 2 processes each method with its parameters seeded from the merged caller context. If at least one caller preloads :profile, the parameter inherits that preload. This handles the helper-method pattern that’s everywhere in Rails controllers.
This is the philosophical decision the entire tool rests on. Every heuristic has knobs. You can lean toward “flag anything that looks suspicious” — high recall, lots of noise, users start ignoring warnings within a week. Or you can lean toward “only flag what we’re confident about” — lower recall, but every warning is actionable.
EagerEye picks the second path. When in doubt, suppress. When a method has multiple callers and only some preload an association, treat it as preloaded (better to miss a real N+1 than to flag a non-issue). When a model isn’t in the parsed set, defer to a small hardcoded list of well-known association names rather than flagging every method call on a loop variable.
The result: in the two production codebases I tested it on, the false positive rate is under 1%. Every flag is worth investigating.
I ran EagerEye through two production Rails apps I work on. Both are 5+ years old, multi-thousand-file codebases with mature test suites. Bullet runs in their dev environment and catches the N+1s that show up in tests. Here’s what EagerEye found on top of that.
| Detector | Issues |
|---|---|
| LoopAssociation | 404 |
| CustomMethodQuery | 184 |
| SerializerNesting | 150 |
| CallbackQuery | 33 |
| PluckToArray | 24 |
| ValidationNPlusOne | 17 |
| MissingCounterCache | 8 |
| ScopeChainNPlusOne | 4 |
| CountInIteration | 2 |
| DelegationNPlusOne | 1 |
| Total | 827 |
I sampled ~50 issues across detectors and manually verified them against the actual code paths. Real positives: 49. False positives: 1 (and that one was in a code path Bullet also can’t see — it’s a “controller passes preloaded relation to a service object in another file” case).
| Detector | Issues |
|---|---|
| SerializerNesting | 118 |
| LoopAssociation | 75 |
| CustomMethodQuery | 17 |
| PluckToArray | 5 |
| CallbackQuery | 4 |
| ScopeChainNPlusOne | 1 |
| Total | 220 |
Same sampling exercise: 100% real positives in my sample.
These aren’t all “production-blocking” issues. Some are admin-export controllers that run once a week. Some are background jobs that happen to be fast despite the N+1 because each query is tiny. But every single one is a place where someone made a decision (intentionally or not) to leave a query-per-iteration pattern in the code, and they probably didn’t know.
The really useful warnings are the ones in hot paths. SerializerNesting in Api::V2::ProductsSerializer rendered millions of times a day is a different problem than a one-off db:seed script. EagerEye flags both, and you decide which to fix.
# Gemfile
gem "eager_eye", group: :development
bundle install
That’s it. No Rails initializer, no config file. From your project root:
eager_eye # scans app/ by default
eager_eye app/controllers app/serializers # specific paths
eager_eye --format json # for CI tools to parse
eager_eye --only loop_association,serializer_nesting # specific detectors
A fresh scan of a typical Rails app finishes in 2-5 seconds.
If you want to suppress detectors or set per-detector severity, generate a config file:
rails g eager_eye:install
That creates .eager_eye.yml:
excluded_paths:
- app/legacy/**
- lib/tasks/**
severity_levels:
loop_association: error
missing_counter_cache: info
min_severity: warning
fail_on_issues: true
fail_on_issues: true makes the CLI exit with a non-zero status when issues are found — the foundation for CI integration.
The whole point of static analysis is that it runs without infrastructure. Here’s a complete GitHub Actions workflow:
name: EagerEye
on: [pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@v1
with:
ruby-version: "3.3"
- run: gem install eager_eye
- run: eager_eye app/
No DB setup, no bundle install of your full Gemfile, no fixtures. The whole job runs in under a minute. If new code introduces a flagged pattern, the build fails and the PR is blocked.
For teams that want non-blocking warnings instead, swap the last line for:
- run: eager_eye app/ --format json > report.json
- run: |
issues=$(ruby -rjson -e 'puts JSON.parse(File.read("report.json"))["summary"]["total_issues"]')
[ "$issues" -gt 0 ] && echo "::warning::Found $issues potential N+1 issues" || true
This uses GitHub Actions’ ::warning:: annotation syntax, which surfaces the issue count directly on the PR without failing the build. Useful during a gradual adoption phase where you want visibility but not enforcement.
For the development loop, a CLI run after every change is friction. EagerEye also ships as a VS Code extension that runs on save and surfaces issues inline:
.pluck(:id) → .select(:id), etc.)The extension is a thin wrapper around the gem — it shells out to the eager_eye binary on save and parses the JSON output. Same analysis engine, same detection, just a smoother feedback loop.
Recommended workflow: extension during development for fast iteration, CLI in CI to gate PRs.
When EagerEye gets it wrong (rare, but it happens), you suppress like RuboCop:
user.posts.count # eager_eye:disable CountInIteration
# eager_eye:disable-next-line LoopAssociation
@users.each { |u| u.profile }
# eager_eye:disable LoopAssociation, SerializerNesting
@users.each { |u| u.posts.each { |p| p.author } }
# eager_eye:enable LoopAssociation, SerializerNesting
# Whole file (must be in first 5 lines)
# eager_eye:disable-file CustomMethodQuery
# With explanation
user.posts.count # eager_eye:disable CountInIteration -- using counter_cache
The -- reason syntax is borrowed from RuboCop and is purely documentation — the linter doesn’t enforce it but reviewers will appreciate it.
Static analysis isn’t magic. Three things EagerEye can’t do today:
Cross-file flow tracking. EagerEye propagates preload context across method calls within the same class. If a controller calls a service object in a different file (OrderProcessor.new(orders).call), the analyzer can’t see that the orders were preloaded. Same applies to renderable view partials.
Runtime metadata. EagerEye doesn’t read your DB schema, doesn’t know if a column has an index, doesn’t know how many records actually live in production. A Post.where(active: true).each looks identical whether active is on 10 records or 10 million. Bullet plus production monitoring (Skylight, Scout, NewRelic) cover this.
Heuristic association detection. When a method is called on an iteration variable but the variable’s model class can’t be inferred, EagerEye falls back to a small hardcoded list of common association names (author, user, posts, etc.). This can miss exotic naming, and very rarely it can over-flag (a column happens to share a name with a common association). The hardcoded list errs on the side of suppression.
The honest summary: use EagerEye alongside Bullet, not instead of it. Static catches code paths Bullet can’t reach; runtime catches what static can’t see. They’re complementary.
The thing I most want to add next is inter-file call graph tracking — propagating preload context not just across same-class methods but across included modules and called service objects. The current implementation handles intra-class flow well; cross-file is the main remaining false-positive source.
Beyond that:
--baseline mode that snapshots existing issues and only fails CI on new ones (so you can adopt EagerEye on a brownfield project without fixing 800 existing warnings on day one)If any of these sound useful, the gem is MIT-licensed and open to PRs:
In the previous post I argued that Bullet only catches the tip of the N+1 iceberg. EagerEye is my attempt at catching most of the rest, automatically, in CI, on every PR — without DB infrastructure, without test fixtures, and without learning a new query DSL.
It won’t catch everything. Static analysis fundamentally can’t. But it shifts the detection point from “after deployment, when production starts paging” to “before merge, when the developer can still fix it cheaply.” That shift is most of what makes a tool useful.
If you try it on a real codebase and find it useful — or find a false positive — open an issue. The whole reason I built this is that the existing tooling left a gap, and the only way to close that gap is to keep iterating on real codebases.
Bullet (currently v8.0.8 as of 2025) detects eager loading issues through ActiveRecord association hooks. However, it remains silent in these scenarios:
.where, .exists?, .find_by)# Bullet WILL NOT CATCH THIS
class User < ApplicationRecord
has_many :teams
def supports?(team_name)
teams.where(name: team_name).exists?
end
end
# In the view - separate query for each user
<% @users.each do |user| %>
<li class="<%= user.supports?("Lakers") ? "purple" : "" %>">
<%= user.name %>
</li>
<% end %>
This code generates 101 queries for 100 users, and Bullet gives no warning.
Bullet hooks into ActiveRecord’s association loading mechanism. When you call user.teams, it tracks whether the association was preloaded. But when you call teams.where(...), you’re creating a new query scope that bypasses the association tracking entirely.
class Order < ApplicationRecord
belongs_to :user
has_many :line_items
def total_with_discount
# Separate query for each order
user.loyalty_tier.discount_rate * line_items.sum(:price)
end
end
# Controller
def index
@orders = Order.includes(:line_items).limit(50)
end
# View - Bullet is silent, but user and loyalty_tier cause N+1
<% @orders.each do |order| %>
<td><%= order.total_with_discount %></td>
<% end %>
def index
@orders = Order
.includes(:line_items, user: :loyalty_tier)
.limit(50)
end
class Order < ApplicationRecord
def total_with_discount(discount_rate = nil)
rate = discount_rate || user.loyalty_tier.discount_rate
rate * line_items.sum(:price)
end
end
# Controller - preload separately, pass to view
def index
@orders = Order.includes(:line_items).limit(50)
user_ids = @orders.map(&:user_id).uniq
@discount_rates = User
.joins(:loyalty_tier)
.where(id: user_ids)
.pluck(:id, "loyalty_tiers.discount_rate")
.to_h
end
Prosopite is an alternative gem that detects N+1s by counting actual SQL queries rather than tracking associations:
# Gemfile
gem 'prosopite'
# config/environments/development.rb
config.after_initialize do
Prosopite.rails_logger = true
Prosopite.raise = true
end
Prosopite will catch the supports? method N+1 that Bullet misses.
ActiveModel::Serializers and similar gems automatically call associations, and these often escape Bullet’s detection.
class PostSerializer < ActiveModel::Serializer
attributes :id, :title, :author_name, :comments_count
def author_name
object.user.name # N+1
end
def comments_count
object.comments.count # N+1 (should use counter_cache)
end
end
# Controller
def index
posts = Post.all
render json: posts # 2 extra queries per post
end
def index
posts = Post.includes(:user, :comments)
render json: posts
end
class PostSerializer < ActiveModel::Serializer
attributes :id, :title, :author_name
belongs_to :user, if: -> { object.association(:user).loaded? }
def author_name
return nil unless object.association(:user).loaded?
object.user.name
end
end
# Gemfile
gem 'batch-loader'
class Post < ApplicationRecord
def author_lazily
BatchLoader.for(user_id).batch do |user_ids, loader|
User.where(id: user_ids).each { |user| loader.call(user.id, user) }
end
end
end
BatchLoader collects all IDs during serialization and executes a single query at the end.
These three methods return the same result but have vastly different performance characteristics.
| Method | Behavior | Query |
|---|---|---|
count |
Always executes COUNT query | SELECT COUNT(*) FROM... |
length |
Loads collection, counts in Ruby | SELECT * FROM... |
size |
Smart: uses length if loaded, count otherwise | Depends on context |
# We eager loaded with includes
@users = User.includes(:posts).where(active: true)
@users.each do |user|
# WRONG: Despite includes, executes COUNT query for each user
puts "#{user.name}: #{user.posts.count} posts"
end
@users.each do |user|
# CORRECT: Counts the loaded collection in Ruby
puts "#{user.name}: #{user.posts.size} posts"
end
For frequently accessed counts, counter_cache is the best solution:
# Migration
add_column :users, :posts_count, :integer, default: 0, null: false
# Model
class Post < ApplicationRecord
belongs_to :user, counter_cache: true
end
# Backfill existing data
User.find_each do |user|
User.reset_counters(user.id, :posts)
end
# Gemfile
gem 'counter_culture'
class Order < ApplicationRecord
belongs_to :customer
counter_culture :customer # orders_count
counter_culture :customer,
column_name: proc { |order| order.cancelled? ? 'cancelled_orders_count' : nil }
end
Database operations inside callbacks can become performance killers, especially during bulk operations.
class Article < ApplicationRecord
after_save :update_search_index
after_save :notify_subscribers
after_save :recalculate_stats
private
def update_search_index
SearchIndex.update(self) # External API call
end
def notify_subscribers
subscribers.each do |sub| # N+1 potential
NotificationMailer.new_article(sub, self).deliver_later
end
end
def recalculate_stats
author.articles.published.count # Query on every save
category.update_article_count! # Update on every save
end
end
# Disaster during bulk import
Article.import(articles_data) # 1000 articles = 3000+ callbacks
class Article < ApplicationRecord
attr_accessor :skip_callbacks
after_save :update_search_index, unless: :skip_callbacks
after_save :notify_subscribers, unless: :skip_callbacks
end
# Bulk import
Article.transaction do
articles_data.each do |data|
Article.create!(data.merge(skip_callbacks: true))
end
end
# Run post-import operations in batch
Article.where(id: imported_ids).find_each(&:update_search_index)
class Article < ApplicationRecord
# Runs after transaction commits
# Safe for Sidekiq jobs
after_commit :notify_subscribers_async, on: :create
private
def notify_subscribers_async
NotifySubscribersJob.perform_later(id)
end
end
# Rails 5+
Notification.suppress do
User.create!(name: "Jane") # Notification callback won't run
end
Choosing the right method is critical when working with large datasets.
# SLOWEST: Load full objects, then map
User.all.map(&:id)
# ~270ms, high memory
# MEDIUM: Select only id, but still creates AR objects
User.select(:id).map(&:id)
# ~100ms, medium memory
# FASTEST: Returns array directly, no AR objects
User.pluck(:id)
# ~15ms, low memory
# PLUCK: When you only need values
user_ids = User.active.pluck(:id)
emails = User.where(role: :admin).pluck(:email)
# SELECT: When you need AR methods
users = User.select(:id, :name, :email)
users.each { |u| puts u.full_display_name } # AR method call
# PLUCK + SUBQUERY: Performant IN clause
Post.where(user_id: User.active.select(:id))
# Single query: SELECT * FROM posts WHERE user_id IN (SELECT id FROM users WHERE...)
# WRONG: pluck with subquery
Post.where(user_id: User.active.pluck(:id))
# Two queries + array held in memory
# Memory-friendly iteration
User.select(:id, :email).find_each(batch_size: 1000) do |user|
process(user)
end
# Even more efficient with postgresql_cursor gem
User.select(:id, :email).each_row do |row|
process(row)
end
Bullet and similar tools catch N+1s, but the real performance problem is sometimes hidden in a single slow query.
# Basic explain
User.where(email: "test@example.com").explain
# Detailed analysis (actually executes the query)
User.where(email: "test@example.com").explain(:analyze)
# More detailed with activerecord-analyze gem
User.where(email: "test@example.com").analyze(
format: :json,
buffers: true,
timing: true
)
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
-- BAD: Sequential Scan (scans entire table)
Seq Scan on users (cost=0.00..1234.00 rows=1 width=244)
(actual time=45.123..89.456 rows=1 loops=1)
Filter: (email = 'test@example.com')
Rows Removed by Filter: 99999
-- GOOD: Index Scan
Index Scan using index_users_on_email on users
(cost=0.42..8.44 rows=1 width=244)
(actual time=0.026..0.027 rows=1 loops=1)
Index Cond: (email = 'test@example.com')
| Situation | Meaning | Solution |
|---|---|---|
Seq Scan on large table |
Index not being used | Add index |
High Rows Removed by Filter |
Too much data being filtered | Optimize WHERE clause |
Sort with high cost |
In-memory sorting | Add index with order |
Hash Join with high cost |
Join not optimized | Add index on FK |
Nested Loop with many loops |
N+1-like situation | Convert to batch query |
# Gemfile
gem 'pghero'
gem 'rails-pg-extras'
# Find slow queries
PgHero.slow_queries
# Unused indexes
PgExtras.unused_indexes
# Index hit rate (below 95% indicates problems)
PgExtras.index_usage
# Migration
add_index :orders, [:user_id, :status, :created_at]
# WORKS (left-to-right matching)
Order.where(user_id: 1)
Order.where(user_id: 1, status: 'pending')
Order.where(user_id: 1, status: 'pending').order(created_at: :desc)
# DOESN'T WORK (user_id skipped)
Order.where(status: 'pending')
# Index only active records
add_index :users, :email,
where: "deleted_at IS NULL",
name: "index_active_users_on_email"
# Index only specific statuses
add_index :orders, :created_at,
where: "status = 'pending'",
name: "index_pending_orders_on_created_at"
# If all columns in SELECT are in the index,
# PostgreSQL doesn't need to access the table
add_index :users, [:email, :name, :role]
# This query is answered entirely from the index
User.where(email: "x@y.com").select(:name, :role)
# Index for LOWER()
execute "CREATE INDEX index_users_on_lower_email ON users (LOWER(email))"
# Query must use the same expression
User.where("LOWER(email) = ?", email.downcase)
# For JSONB columns
add_index :products, :metadata, using: :gin
# For array columns
add_index :articles, :tags, using: :gin
# For full-text search
execute <<-SQL
CREATE INDEX index_articles_on_search ON articles
USING gin(to_tsvector('english', title || ' ' || content))
SQL
# Gemfile (development group)
group :development do
gem 'bullet' # N+1 detection (associations)
gem 'prosopite' # N+1 detection (query counting)
gem 'rack-mini-profiler' # Request profiling
gem 'memory_profiler' # Memory allocation
gem 'activerecord-analyze' # EXPLAIN ANALYZE
gem 'rails-pg-extras' # PostgreSQL insights
end
# Using n_plus_one_control gem
# spec/rails_helper.rb
require 'n_plus_one_control/rspec'
RSpec.describe UsersController, type: :request do
context 'N+1 detection' do
populate { |n| create_list(:user, n, :with_posts) }
it 'does not have N+1 queries' do
expect { get '/users' }.to perform_constant_number_of_queries
end
end
end
# Gemfile
gem 'skylight' # Performance monitoring
gem 'scout_apm' # Alternative
gem 'newrelic_rpm' # Alternative
# Custom slow query logging
# config/initializers/slow_query_logger.rb
ActiveSupport::Notifications.subscribe('sql.active_record') do |*, payload|
duration = payload[:duration]
if duration > 100 # Over 100ms
Rails.logger.warn "[SLOW QUERY] #{duration.round(2)}ms: #{payload[:sql]}"
end
end
# .github/workflows/test.yml
- name: Run tests with Bullet
env:
BULLET_ENABLED: true
run: bundle exec rspec
# spec/rails_helper.rb
if ENV['BULLET_ENABLED']
Bullet.enable = true
Bullet.raise = true # Fail CI on N+1
end
Bullet is a fantastic tool, but it only catches the tip of the iceberg. For real performance optimization:
The key insight: Bullet tracks association loading, not query execution. Any code path that generates queries without going through standard association loading will be invisible to Bullet.
By the end of this guide, you’ll have a fully functional authentication system that handles user registration, login, profile management, and image uploads—all working smoothly with Turbo.
Devise is the de facto standard for authentication in Rails applications. It provides a complete MVC solution with modules for password recovery, session management, email confirmation, and more.
bundle add devise
rails generate devise:install
rails generate devise:views
rails generate devise User
After running the generator, Devise will create a migration file in db/migrate/. Before running the migration, let’s add some custom fields to our User model.
Open the generated migration file and add the following fields within the create_table block:
# db/migrate/XXXXXX_devise_create_users.rb
def change
create_table :users do |t|
## Database authenticatable
t.string :email, null: false, default: ""
t.string :encrypted_password, null: false, default: ""
# ... other Devise fields ...
## Custom Fields
t.string :name_surname, null: false, default: ""
t.string :gsm
t.date :date_of_birth
t.timestamps null: false
end
add_index :users, :email, unique: true
add_index :users, :reset_password_token, unique: true
end
When adding custom fields, we need to permit them in Devise’s strong parameters. First, update your routes to use a custom registrations controller:
# config/routes.rb
Rails.application.routes.draw do
devise_for :users, controllers: { registrations: "users/registrations" }
# ... other routes ...
end
Then create the custom controller:
# app/controllers/users/registrations_controller.rb
class Users::RegistrationsController < Devise::RegistrationsController
before_action :configure_sign_up_params, only: [:create]
before_action :configure_account_update_params, only: [:update]
protected
def configure_sign_up_params
devise_parameter_sanitizer.permit(:sign_up, keys: [:name_surname, :gsm, :date_of_birth])
end
def configure_account_update_params
devise_parameter_sanitizer.permit(:account_update, keys: [:name_surname, :gsm, :date_of_birth])
end
end
Now run the migration:
rails db:migrate
Hotwire (HTML Over The Wire) is Rails’ answer to building reactive applications without writing custom JavaScript. However, Devise was built before Hotwire existed, so we need to make a few adjustments to ensure they work together smoothly.
By default, when Devise encounters an authentication error (invalid credentials, unauthorized access, etc.), it responds with HTTP status codes that Turbo doesn’t handle gracefully. This can result in broken redirects or missing flash messages.
To handle authentication failures properly with Turbo, create a custom failure app:
# lib/turbo_failure_app.rb
class TurboFailureApp < Devise::FailureApp
def respond
if request_format == :turbo_stream
redirect
else
super
end
end
def skip_format?
%w[html turbo_stream */*].include?(request_format.to_s)
end
end
Update your Devise initializer to use the custom failure app:
# config/initializers/devise.rb
# Ensure the custom failure app is loaded
require "turbo_failure_app"
Devise.setup do |config|
# ... other configurations ...
# Add turbo_stream to navigational formats
config.navigational_formats = ["*/*", :html, :turbo_stream]
# Configure Warden to use our custom failure app
config.warden do |manager|
manager.failure_app = TurboFailureApp
end
end
| Component | Purpose |
|---|---|
TurboFailureApp |
Intercepts authentication failures and ensures proper redirect behavior for Turbo Stream requests |
skip_format? |
Allows the failure app to handle HTML, Turbo Stream, and wildcard formats |
navigational_formats |
Tells Devise which response formats should trigger redirects instead of 401 responses |
With this configuration, your Devise authentication will work seamlessly with Turbo Drive and Turbo Frames.
Simple Form is a powerful form builder that reduces boilerplate and integrates beautifully with CSS frameworks like Bootstrap and Tailwind.
bundle add simple_form
rails generate simple_form:install
# For Bootstrap projects:
rails generate simple_form:install --bootstrap
Let’s refactor the Devise login page to use Simple Form with Tailwind CSS styling:
<%# app/views/devise/sessions/new.html.erb %>
<div class="max-w-md mx-auto bg-white shadow-lg rounded-lg p-8 border border-gray-300">
<h2 class="text-3xl font-bold text-center mb-8 text-gray-800">Log in</h2>
<%= simple_form_for(resource, as: resource_name, url: session_path(resource_name)) do |f| %>
<div class="space-y-4">
<%= f.input :email,
label: "Email",
required: true,
autofocus: true,
input_html: {
autocomplete: "email",
class: "mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-blue-500 focus:border-blue-500"
} %>
<%= f.input :password,
label: "Password",
required: true,
input_html: {
autocomplete: "current-password",
class: "mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-blue-500 focus:border-blue-500"
} %>
<% if devise_mapping.rememberable? %>
<%= f.input :remember_me,
as: :boolean,
label: "Remember me",
wrapper_html: { class: "flex items-center" },
input_html: { class: "h-4 w-4 text-blue-600 border-gray-300 rounded" } %>
<% end %>
<%= f.button :submit,
"Log in",
class: "w-full py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 transition duration-150" %>
</div>
<% end %>
<div class="mt-6 text-center text-sm text-gray-600">
<%= render "devise/shared/links" %>
</div>
</div>
Active Storage provides a simple way to attach files to Active Record models. Combined with the image_processing gem, we can handle user profile images with validation and transformations.
First, uncomment the image_processing gem in your Gemfile:
# Gemfile
gem "image_processing", "~> 1.2"
Then install and set up Active Storage:
bundle install
rails active_storage:install
rails db:migrate
Update the User model to accept profile images:
# app/models/user.rb
class User < ApplicationRecord
devise :database_authenticatable, :registerable,
:recoverable, :rememberable, :validatable
has_one_attached :profile_image
validate :acceptable_image
private
def acceptable_image
return unless profile_image.attached?
# Validate file size (max 10MB)
if profile_image.byte_size > 10.megabytes
errors.add(:profile_image, I18n.t("errors.messages.profile_image_too_large", default: "is too large (maximum is 10MB)"))
end
# Validate content type
acceptable_types = ["image/jpeg", "image/jpg", "image/png", "image/webp"]
unless acceptable_types.include?(profile_image.content_type)
errors.add(:profile_image, I18n.t("errors.messages.profile_image_invalid_format", default: "must be a JPEG, PNG, or WebP image"))
end
end
end
Add the file input to your edit registration view:
<%# app/views/devise/registrations/edit.html.erb %>
<%= simple_form_for(resource, as: resource_name, url: registration_path(resource_name), html: { method: :put, multipart: true }) do |f| %>
<%# ... other fields ... %>
<div class="space-y-2">
<% if resource.profile_image.attached? %>
<div class="mb-4">
<%= image_tag resource.profile_image.variant(resize_to_limit: [150, 150]),
class: "rounded-full border-2 border-gray-200" %>
</div>
<% end %>
<%= f.input :profile_image,
as: :file,
label: "Profile Image",
hint: "Accepted formats: JPEG, PNG, WebP. Maximum size: 10MB",
input_html: {
accept: "image/jpeg,image/png,image/jpg,image/webp",
class: "block w-full text-sm text-gray-500 file:mr-4 file:py-2 file:px-4 file:rounded-md file:border-0 file:text-sm file:font-semibold file:bg-blue-50 file:text-blue-700 hover:file:bg-blue-100"
} %>
</div>
<%# ... submit button ... %>
<% end %>
Don’t forget to permit the profile_image parameter in your registrations controller:
# app/controllers/users/registrations_controller.rb
def configure_account_update_params
devise_parameter_sanitizer.permit(:account_update, keys: [:name_surname, :gsm, :date_of_birth, :profile_image])
end
We’ve built a complete, modern authentication system that combines the reliability of Devise with the reactivity of Hotwire. Here’s what we accomplished:
This setup provides a solid foundation that you can extend with additional features like OAuth providers, two-factor authentication, or email confirmation as your application grows.