Recently I'd an opportunity to try out the Hanami framework by building one of the microservices for our client.

I was hyped. I've been watching the Hanami development for quite some time already and I could not wait anymore to try it out in a real project.

It was extremely kind that our client, Yousty AG, in the spirit of innovation, invested in trying out this completely new (for our team) ruby framework.

Here is how it went.

The scope

I was going to develop a favoriting service.

In Yousty we embrace the microservice architecture, and favoriting was the next feature we wanted to extract from our big monolith.

Yousty is a great company, encouraging developers to try out new things, new solutions, and tech stacks, but at the same time, it's important to manage the business risk while doing that.

Trying out the whole new framework is not the smallest thing to do, so we needed to tackle this topic carefully.

But WHY take the risk at all?

The explanation of why one could not choose Rails as an application framework is worthy of a separate article. I'll not go into the details, but some of the reasons to not use Rails had already been covered, so I recommend checking that.

We've experienced more and more troubles with Rails the more we scaled up our business and the more complicated problems we're up to solve. But also, we're in the mindset of not sticking with any particular technology ONLY because we know it. It's a very, dangerous thing, to become too comfortable with the known architecture, tech stack, or processes - we could easily miss the great opportunities to evolve and to stay on top of the competition.

Innovation is an important aspect of technology and I am one of the people that really encourage others to try new things out.

The service

The favoriting service, with only 4 API endpoints, was the perfect candidate for an innovation. It's so small, that in case of failure, rewriting it to Rails would take maybe a day or so and it's not a key feature for our business.

So the risk was really small, and we've got a green light to try Hanami 2.0 out.

My initial mistakes

First of all, let's go through one of the two biggest mistakes I did during the implementation of the service in Hanami.

1. Hanami looked abandoned.

I knew that Hanami was in a process of complete refactoring at the time, and there was intense work being done to wrap-up the version 2.0, but I needed to ensure that the project is active, that people are engaged and the development is really intense.

I've gone through the GitHub insights then there was a first big surprise waiting for me.

There was almost NO update whatsoever in the Hanami main repository for the last 6 months! That did not look promising. I tried to check out the master branch activity, and realized, that it's pointing to version 1.3, but I could not even find the Hanami 2.0 branch...

This was an issue, but had been recently fixed by a repository cleanup - now the default main branch, actually stores the newest code.

So I reached out to the core team, asking where is the work being done and they calmed me down. Piotr Solnica explains it also in one of his recent Hanami talks

Mono-Repo vs multiple repositories

First of all, Hanami is split into the independent components, and the main repository just glues all of them together - there is no need for too much work within the main repository, but rather within each of the components.

This is a fundamental difference in relation to for example Rails, where there is a big mono-repo - that sums the activity from all of the components together!

Rails repository view - components list

So It was really important to realize, that to check the real activity within the Hanami framework, we needed to see the bigger picture, and look into different repositories.

ROM + DRY + Hanami

The other very important information to highlight was that Hanami 2.0 is built by combining three big gem families.

  • DRY-RB gems - a collection of independent libraries, each of which performs a single task, and together is a powerful toolset for ruby applications.
  • ROM-RB - an extremely powerful and flexible persistence framework, allowing to connect to any kind of data store.
  • Hanami components - all the hanami components, built to easily create complete, scalable ruby applications.

It turns out, that to make Hanami 2.0 possible, the authors of all those three gem families needed to join forces, and put tremendous work into each of them to adjust, stabilize, and improve all the gems Hanami would use in the next major release.

When I've realized that, I finally got satisfied. People WERE working on Hanami. Actually they work like crazy and it was a relatively low risk that this project would be abandoned.

2. The misleading Hanami-API

I've seen a blog post in the official Hanami blog, published by Tim Riley, about introducing Hanami::API.

He published some crazy benchmark results, showing how performant Hanami::API is in relation to rails

Hanami runtime benchmark results

For full benchmarks, I strongly recommend reading the original post.

All was fine, except that I've come from a Rails world. I've used Rails::API for years! And when I've seen the Hanami::APi name, I immediately assumed, that it's a complete Hanami APP, but without views...

Which was a completely wrong assumption that caused unnecessary delay.

I've started a project using Hanami::API, and I quickly realized, that it's far from calling it a "complete" application framework. The amount of configuration required was just crazy, and the lack of resources available on the web was quite challenging.

After a while, I reached out to the Hanami core team again, and they explained my mistake.

Hanami API is not meant to be used as a complete web framework.

It appears, that in Hanami you can switch on and off every component you like! There is no hard dependency on views or given persistence engine, so there is no need to create a subproject specific for API needs.

In fact, Hanami is so flexible, you can adjust it to work with anything.

Don't you need a database at all?

Disable it - or remove completely.

Don't you need a WEB interface, router, at all?

Disable it - or remove completely.

The Hanami::API was just a tiny web part with a router extracted, so we can use it in very tiny applications, similar to Sinatra.

After I've got that information, I just needed to hit my desk with my head a few times...

Head Desk

...and then start again - this time properly.

Writing a Hanami 2.0 service application

Writing the complete application from scratch was easier than I expected. I needed to go through ROM-rb guides, and it was frustrating sometimes, that as a senior Ruby developer I needed to check the syntax for a find method, or how to write tests for the router... but those were minor slowdowns.

Maybe because of how we already worked with our Rails services, putting most of our business logic in the lib folder, or maybe because of not being afraid of additional abstractions and keeping our Rails models empty, with only persistence information... Whatever it was, it was really easy for me to write the app in Hanami, and everything worked out of the box.

It was easy, it was working, I was able to pull the complete application together even before the first alpha version of Hanami 2.0 had been released.

That was super promising.

The final decision

Then we had a call in our team and we've decided to rewrite this app to Rails.

Are you surprised? So let me explain.

To make a final decision I needed to consider a few factors.

1. Easiness to teach the team a new framework without slowing down.

Because of the very early stage of the Hanami 2.0, there was not too much community built behind the project just yet, and therefore there were not enough resources available, to easily teach our team the new framework without slowing down too much.

I immediately addressed that issue by starting the Hanami Mastery project, producing video guides, articles, and tutorials to help new developers master Hanami as quickly and effortless as possible.

But I am an innovator and early adopter of any promising technology I face - however, I'd never force anybody to do the same. I can help to make things easier, help to build community, I can lead - but not force my team to pawn the way for others.

2. The infrastructure overhead.

Again, because of the early stage, there were quite a few things that I needed to write from scratch - and we already solved them in our Rails applications. Things like app scaffold generators, the deployment scripts, etc.

The main issue was that when we've been writing our solutions we didn't think too much about having our components rails-independent, nor it would be always an easy thing to keep in mind.

Anyway, it was an additional slowdown, and the more complicated projects we would do, the more such stuff we would need to rewrite.

3. The Hanami team size, and development speed.

Then the third factor that I've seen a bit risky for my client, was the size of the core team and the deadlines they commited to fulfill.

Hanami 2.0 was already a year after the targeted release, and It was probably a year yet before the official, stable version would be launched.

As I am an open-source committer myself, I quickly realized why it happened. It's not that I demand anybody in the Open Source world to stick to any kind of deadlines.

Also, it was MY issue, that I'd been seen a "goal" as some kind of "promise", which caused the wrong assumptions.

On the other hand, until the project becomes really popular and gets meaningful sponsoring, people working on the Open Source projects work in their spare time, without getting paid for the great job they do! They work during nights and on weekends, to make OUR lives easier.

That's a heroic work that I could never appreciate enough. Still, there is a lot of expectations when it comes to Open-Source projects, but not so much will of supporting financially people's work to speed things UP.

This is another reason Why I've started the Hanami Mastery initiative - to inspire others for better support of great Open Source projects. You can read more about how I see the Open Source financing and how I've decided to improve in that field.

However, regardless of what I think personally, my job is to minimize the risk my clients take while maximizing the effect of certain actions.

This is why I pointed it as a big problem, and while I've decided to improve on this domain, I also recommended waiting before switching.


Sometimes it's hard to decide whether to use the given technology or not. The ability to go around the "hype", put emotions aside, and just calculate decisions while having the client's interest in their mind is an extremely important skill and this is what I wish you all to have. I was lucky enough to work with a great team that helps me making such hard decisions.

Hanami is a great choice, and in my personal opinion, it's a framework of choice for the near future, but it needs some time yet to stabilize the 2.0 version. Also, it needs the time for building the library of learning resources around the project which I'm proudly helping with.

I hope we'll be able to try again in 2022, as Hanami by default solves most of the problems we've faced with Rails.

And until that happens, I'll work hard on Hanami Mastery initiative to help solving all the issues we've faced during this experience!