Micro-slices in Hanami

Slices are my favourite architectural feature in Hanami. They allude to the vertical slices architecture and let you host cross-functional “mini-apps” within your main Hanami projectThe feature itself is present from early days of Hanami, perhaps from the times when it was still called Lotus. Back then it was called apps..

A typical slice file structure (generated by Hanami slice generator) would look like this:

slices
└── admin
    ├── action.rb
    ├── actions
    ├── assets
    │   ├── css
    │   │   └── app.css
    │   ├── images
    │   │   └── favicon.ico
    │   └── js
    │       └── app.js
    ├── db
    │   ├── relation.rb
    │   ├── repo.rb
    │   └── struct.rb
    ├── operation.rb
    ├── relations
    ├── repos
    ├── structs
    ├── templates
    │   └── layouts
    │       └── app.html.erb
    ├── view.rb
    └── views
        └── helpers.rb

14 directories, 11 files

This is a great foundation to build a comprehensive, large slice, such as an admin panel. However, it feels a bit overwhelming for smaller-scope things.

Yesterday, while spelunking through Hanami internals, looking for a way to distribute a slice as a gemUnfortunately, I think it’s not easily done right now., I stumbled upon another way to define a slice. It is not described in the Guides, but is documented in the code - so I treat it as official.

The trick is this:

1. Drop a file into config/slices (a directory that doesn’t exist in a stock Hanami app)
2. That’s it. No subdirectory army required.

Let’s build one.

The tutorial part

We will start by creating a new Hanami app and creating a dir and a file.

hanami new myapp
cd myapp
mkdir config/slices
touch config/slices/healthcheck.rb

Now we will put an ultra-simple slice inside:

module Healthcheck
  class Slice < Hanami::Slice
  end
  
  class Routes < Hanami::Routes
    get "/", to: ->(_env) { [200, 
      {"Content-Type" => "application/json"}, 
      ['{"status": "ok"}']] }
  end
end

Finally, we mount this in our main app, in config/routes.rb:

module Myapp
  class Routes < Hanami::Routes
    slice :healthcheck, at: "/health"
  end
end

Now if we start the app, we can check that it works:

$ curl -i localhost:2300/health
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 16

{"status": "ok"}

Our micro-slice is up and running.

Why reach for micro-slices

As shown above, this is a great way to create a very focused, small slice, without all the ceremony of creating a directory in the slices directory. It might be useful if you mainly organize the slices by domain boundaries, but still need a couple of “technical” (non-domain) ones, for example to expose some metrics or to have an admin dashboard.

In absence of a good way to have externally packaged slices supported in Hanami… yet. I would like, at some point, to find time to try to solve this., it might pave the way to ship a “slice builder” in a gem.

Imagine shipping an “admin slice DSL” from a gem.

# config/slices/admin.rb
module Admin
  extend GemifiedAdminPanelSliceBuilder
  
  admin do
    section "E-Commerce" do
      page "Orders", schema: ECommerce::Schemas::Order
      page "Products", schema: ECommerce::Schemas::Product
      page "Shipping methods", schema: ECommerce::Schemas::ShippingMethod
    end
  end
end

The gem isn’t the admin slice — it just gives you a way to build one. This is still day-dreaming, but micro-slices show a legit path towards this goal.

Meanwhile, we can all enjoy our micro-slices, if needed.