Hanami: a full-stack Ruby web framework built from single-purpose libraries

What Hanami solves, and who it is for

The README describes Hanami as "a flexible framework for maintainable Ruby apps" and as a full-stack framework made up of smaller, single-purpose libraries. That sentence is the whole pitch. The repository you are reading is not the router or the view layer; it is the glue that ties Hanami::Router, Hanami::Action, Hanami::View, Hanami::DB and Hanami::Assets together into one application.

The intended reader is a Ruby developer who has decided that a framework should be a small set of composable parts rather than one large object graph. The README states that these components are designed to be used independently or together in a Hanami application. That is the practical difference: you can take Hanami::Router into an existing Rack stack without adopting the rest, or you can take all five and get a full-stack app.

The project is not aimed at someone who wants the framework to decide where every file goes. Hanami still generates a project skeleton, but the value it claims is flexibility and maintainability, both of which are properties you have to hold onto yourself once the skeleton exists.

How the five libraries fit together

The architecture is a hub and spokes. This gem provides the glue; the spokes are separate repositories, each with its own release cycle. Hanami::Router handles HTTP routing and is described as Rack compatible. Hanami::Action provides actions for Rack, described as full featured, fast and testable. Hanami::View separates views from templates, which means presentation logic lives in a Ruby object and the template stays declarative. Hanami::DB covers database integration with migrations, repositories, relations and structs. Hanami::Assets handles asset management.

That split has a visible consequence in the repository layout. The top-level entries include a Gemfile, a Gemfile.devtools, a Rakefile, a gemspec and a package.json, and the package.json pulls in hanami-assets from GitHub plus TypeScript as a dev dependency. So the framework's own tooling spans both Ruby and Node, even though the primary language is Ruby. If your build environment has no Node, the asset side is the part to check first.

Because the components are separate gems, upgrading one is not the same operation as upgrading the framework gem. The glue can move without the router moving, and vice versa.

Installing Hanami and running your first app

The README gives a two-step install. First the gem itself:

gem install hanami

Then the generator, which creates a project, installs its dependencies and starts a development server:

hanami new bookshelf
cd bookshelf && bundle
bundle exec hanami dev

The README says that after `bundle exec hanami dev` you should visit http://localhost:2300. That port is the framework's default development port, and it is worth noting because it is not the port most Ruby developers expect.

The README points to the Getting Started guide at guides.hanamirb.org for the rest. It does not document the generated directory structure, the configuration format, or how to add a route in this file, so treat the generator output and the guide as the source of truth rather than the README.

If you are working on the framework itself rather than an app, the README lists the test commands: `bundle exec rake` for the full suite, `bundle exec rspec spec/unit` for unit tests, `bundle exec rspec spec/integration` for integration tests, and `bundle exec rspec path/to/spec.rb` for a single file.

Where Hanami asks more of you than Rails does

The trade-off is explicit in the component list. Five libraries means five things to learn, five changelogs to follow and five sets of concepts to keep straight. Hanami::DB alone introduces migrations, repositories, relations and structs as separate ideas. A developer coming from a convention-heavy framework will find that Hanami makes them name things the framework would otherwise infer.

The second limitation is ecosystem shape. The README names five components and no more. There is no list of third-party integrations, no plugin directory, no statement about which background job library or authentication library to use. If your project depends on a wide shelf of pre-built pieces, the README gives you nothing to evaluate that against, and you would be choosing Hanami on the strength of its own five libraries alone.

The third is documentation surface. The README is short and delegates almost everything to the Getting Started guide and the API documentation at rubydoc.info. Anything not in those two places, including the generated app's internal layout, is not described in the README. That is a real cost during onboarding.

Hanami compared with Rails

The honest comparison is with Rails, because that is the default choice for a full-stack Ruby web application and Hanami is positioned as the alternative.

The difference in approach is structural. Rails ships as one framework with a large set of built-in components that assume each other's presence. Hanami ships as a glue gem over five libraries that the README says are designed to be used independently. In Rails, pulling out the router means fighting the framework. In Hanami, taking only Hanami::Router into an existing Rack app is a supported use, because that is how the component is described.

The second difference is where decisions live. Rails decides for you and lets you override. Hanami's stated value is flexibility, which means the decisions are yours from the start. That is better when your application has unusual boundaries and worse when it does not, because you spend time on choices the other framework would have made silently.

Neither is faster to a first page. Hanami's generator gets you to localhost:2300 with three commands, which is comparable. The divergence appears a few weeks in, when the number of components you have had to understand becomes visible.

Release cadence, licence and what upgrading costs

The repository is not archived, and the last push was on 2026-09-20. Recent releases are v3.0.0 on 2026-07-01, v3.0.1 on 2026-07-03 and v3.0.2 on 2026-08-21. That is a 3.0 line with two patch releases inside two months, which tells you the maintainers are still settling the major version.

The MIT licence is stated in the repository metadata and the README points to the LICENSE file for the text. MIT is permissive, so it places few constraints on how you use or redistribute the framework. That is a statement about the licence identifier, not legal advice; read the LICENSE file and your own organisation's policy.

The upgrade cost is the part the README does not settle. Because the framework is glue over five separately versioned libraries, a Hanami upgrade can require corresponding upgrades in Hanami::Router, Hanami::Action, Hanami::View, Hanami::DB and Hanami::Assets. The README does not document a rollback procedure or a compatibility matrix, so pinning versions in your Gemfile and reading the CHANGELOG.md at the repository root before a major bump is the only path the documentation supports.

Editorial conclusion

Adopt Hanami when you want the HTTP, view and persistence layers to be separate gems you can reason about one at a time, and when your team is comfortable reading the Getting Started guide before writing code. Do not adopt it if you need a large catalogue of ready-made gems to drop in, because the README lists five components and nothing else. Before committing, run hanami new against the current gem, confirm the generated app bundles cleanly, and check that the Hanami::DB and Hanami::Assets versions pulled in match what your deployment expects.

Frequently asked questions

Official sources

1. hanami/hanami on GitHub
2. License: MIT
3. Project website
4. README
5. Releases