Hanami
Modern Ruby web framework built on clean architecture principles — an alternative to Rails for teams that want explicit dependencies, interactors, repositories, and strict separation of concerns. Hanami 2.0 (2022) was a near-complete rewrite: dry-rb ecosystem integration (dry-container, dry-auto_inject), ROM (Ruby Object Mapper) for data persistence instead of ActiveRecord, functional core/imperative shell patterns. No magic, no monkey patching — Hanami apps are plain Ruby objects with explicit wiring. Better testability, smaller memory footprint, faster boot times than Rails.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
No monkey patching reduces attack surface vs Rails. Explicit dependencies make security audits easier. CSRF protection via hanami-csrf. No default auth — application responsibility. dry-validation for input sanitization.
⚡ Reliability
Best When
You're building a long-lived Ruby application and want explicit architecture, dependency injection, and ROM-based persistence instead of Rails magic and ActiveRecord coupling.
Avoid When
You need Rails ecosystem gems (Devise, ActiveAdmin, etc.), are prototyping quickly, or your team is already productive with Rails. Hanami's learning curve isn't justified for small projects.
Use Cases
- • Build Ruby agent API backends using clean architecture principles — Hanami's interactor/repository pattern makes agent workflows explicit and testable without ActiveRecord magic
- • Create modular agent service applications using Hanami's slice architecture — each domain slice (users, agents, billing) has isolated dependencies and can be deployed independently
- • Develop Rails-alternative Ruby APIs with strict dependency injection using dry-auto_inject — every dependency is explicit, making agent service dependencies auditable
- • Build high-performance Ruby APIs — Hanami's smaller footprint and explicit routing have lower memory overhead and faster boot times than equivalent Rails apps
- • Use Hanami with ROM (Ruby Object Mapper) for explicit data access — ROM's repository pattern makes database queries explicit and testable without ORM magic
Not For
- • Teams that want Rails conventions and ecosystem — Devise, ActiveAdmin, and most Rails gems don't work with Hanami; smaller ecosystem means fewer drop-in solutions
- • Rapid prototyping — Hanami's explicit architecture requires more upfront wiring than Rails; scaffolding is less magical; better for long-lived production apps than quick experiments
- • Developers expecting ActiveRecord — Hanami uses ROM for persistence; ActiveRecord patterns (model.save, model.where) don't apply; ROM has different mental model
Interface
Authentication
Hanami doesn't include authentication. Use jwt gem, rodauth (Hanami-compatible), or custom Rack middleware for auth. Devise is Rails-specific and doesn't work with Hanami.
Pricing
Hanami is MIT licensed and community-maintained. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Hanami 2.0 is a complete rewrite from 1.x — Hanami 1.x and 2.x are incompatible; community resources for 1.x don't apply to 2.x; always specify version when searching docs
- ⚠ dry-auto_inject for dependency injection — all dependencies injected via constructor; testing requires providing mock implementations in the container; global state injection pattern different from Rails mocks
- ⚠ ROM (Ruby Object Mapper) instead of ActiveRecord — ROM uses repository pattern with explicit mapping between relations and entities; no model.save or model.where; write ROM relations and repo methods explicitly
- ⚠ Slice architecture for large apps — Hanami 2.0 organizes code into slices (app/slices/admin/, app/slices/api/); each slice has own container; cross-slice dependencies must be explicit
- ⚠ Authentication not included — unlike Rails + Devise, Hanami has no canonical auth gem; rodauth works but requires manual Hanami integration; JWT auth via rack middleware is common pattern
- ⚠ Smaller ecosystem means manual wiring — background jobs (Sidekiq), file uploads (Shrine), etc. require manual integration without Hanami-specific gems; integration follows Rack standards but requires more code
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Hanami.
Scores are editorial opinions as of 2026-03-06.