Hanami — Lightweight Full-Stack Ruby Web Framework

Introduction

Hanami is a full-stack Ruby web framework that takes a different approach from Rails. It favors explicit over implicit behavior, separates persistence from domain logic, and organizes code into self-contained slices. Hanami 2.x is built on top of dry-rb libraries, making it a strong choice for Ruby developers who want clean architecture without leaving the Ruby ecosystem.

What Hanami Does

• Scaffolds full-stack Ruby web applications with a modular slice architecture
• Separates actions, views, and persistence into distinct layers
• Uses dry-rb ecosystem (dry-validation, dry-types) for type-safe parameter handling
• Provides a ROM-based persistence layer decoupled from the web framework
• Supports asset compilation and template rendering with ERB or Haml

Architecture Overview

Hanami 2.x is built on a dependency injection container powered by dry-system. Applications are divided into slices — self-contained modules that encapsulate routes, actions, and business logic. Each HTTP request hits a router that dispatches to an action class. Actions receive validated parameters and return a response, with no implicit global state. Persistence uses ROM (Ruby Object Mapper) with repositories and relations, keeping SQL concerns separate from domain objects.

Self-Hosting & Configuration

• Install with gem install hanami (Ruby 3.1+)
• Generate a new project with hanami new myapp --database=postgres
• Configure database connections in config/settings.rb
• Run migrations with bundle exec hanami db migrate
• Deploy with Puma behind Nginx, similar to any Rack-based Ruby application

Key Features

• Slice-based architecture for modular monoliths and bounded contexts
• Action classes with explicit input validation using dry-validation
• ROM persistence layer that avoids Active Record pattern pitfalls
• Thread-safe by default with no mutable global state
• Strong type system integration via dry-types

Comparison with Similar Tools

• Ruby on Rails — convention-over-configuration with Active Record, larger ecosystem, more implicit behavior
• Sinatra — minimal DSL for simple apps, no built-in persistence or architecture patterns
• Roda — routing-tree based micro framework, extremely fast, less opinionated about structure
• Grape — REST API framework for Ruby, often mounted inside Rails, API-focused only

FAQ

Q: Should I choose Hanami over Rails for a new project? A: Hanami suits teams that value explicit architecture and want to avoid the implicit coupling common in large Rails applications. Rails remains better for rapid prototyping and access to its vast gem ecosystem.

Q: Does Hanami support WebSockets? A: Not natively in the core framework. You can integrate Action Cable or use a standalone WebSocket library alongside Hanami.

Q: Can I use ActiveRecord with Hanami? A: Hanami is designed around ROM, but technically you can bring in ActiveRecord as a gem. The framework encourages using its own persistence layer for consistency.

Q: How mature is Hanami 2.x? A: Hanami 2.x is production-ready with stable releases. The community is smaller than Rails but active, with documentation and guides available.

Sources

• https://github.com/hanami/hanami
• https://hanamirb.org