You can think of slices as distinct modules of your application. A typical case is to use slices to separate your business domains (for example billing, accounting or admin) or to have separate modules for a particular feature (API) or technical concern (search).

Slices exist in the slices directory.

Hanami provides a slice generator. To create an API slice, run bundle exec hanami generate slice api.

This creates a directory in slices, adding some slice-specific classes like actions:

Simply creating a new directory in slices will also create a slice:

  1. mkdir -p slices/admin
  3. slices
  4. └── admin

Features of a slice

Slices offer much of the same behaviour and features as the Hanami app.

A Hanami slice:

  • has its own container
  • imports a number of standard components from the app
  • can have its own providers (e.g. slices/api/providers/my_provider.rb)
  • can include actions, routable from the application’s router
  • can import and export components from other slices
  • can be prepared and booted independently of other slices
  • can have its own slice-specific settings (e.g. slices/api/config/settings.rb)

Like Hanami’s app folder, components added to a Hanami slice are automatically organised into the slice’s container.

For example, suppose our Bookshelf application, which catalogues international books, needs an API to return the name, flag, and currency of a given country. We can create a countries show action in our API slice (by running bundle exec hanami generate action countries.show --slice api or by adding the file manually) that looks like:

  1. # slices/api/actions/countries/show.rb
  3. require "countries"
  5. module API
  6.   module Actions
  7.     module Countries
  8.       class Show < API::Action
  9.         include Deps[
  10.           query: "queries.countries.show"
  11.         ]
  13.         params do
  14.           required(:country_code).value(included_in?: ISO3166::Country.codes)
  15.         end
  17.         def handle(request, response)
  18.           response.format = :json
  20.           halt 422, {error: "Unprocessable country code"}.to_json unless request.params.valid?
  22.           result = query.call(
  23.             request.params[:country_code]
  24.           )
  26.           response.body = result.to_json
  27.         end
  28.       end
  29.     end
  30.   end
  31. end

This action uses the countries gem to check that the provided country code (request.params[:country_code]) is a valid ISO3166 code and returns a 422 response if it isn’t.

If the code is valid, the action calls the countries show query (aliased here as query for readability). That class might look like:

  1. # slices/api/queries/countries/show.rb
  3. require "countries"
  5. module API
  6.   module Queries
  7.     module Countries
  8.       class Show
  9.         def call(country_code)
  11.           {
  12.             name: country.iso_short_name,
  13.             flag: country.emoji_flag,
  14.             currency: country.currency_code
  15.           }
  16.         end
  17.       end
  18.     end
  20. end

As an exercise, as with Hanami.app and its app container, we can boot the API::Slice to see what its container contains:

  1. bundle exec hanami console
  3. bookshelf[development]> API::Slice.boot
  4. => API::Slice
  5. bookshelf[development]> API::Slice.keys
  6. => ["settings",
  7.  "actions.countries.show",
  8.  "queries.countries.show",
  9.  "inflector",
  10.  "logger",
  11.  "notifications",
  12.  "rack.monitor",
  13.  "routes"]
  1. bookshelf[development]> API::Slice["queries.countries.show"].call("UA")
  2. => {:name=>"Ukraine", :flag=>"🇺🇦", :currency=>"UAH"}

Standard app components

Since every slice is part of the larger app, a number of standard app components are automatically imported into each slice. These include:

  • "settings" — the app’s
  • "inflector" — the app’s inflector
  • "logger" — the app’s logger
  • "routes" — the app’s routes helper

If you have additional components in your app that you wish to make available to each slice, you can configure these via config.shared_app_component_keys:

Think carefully before making components available to every slice, since this can create an undesirable level of coupling between the slices and the app. Instead, you may wish to consider slice imports and exports.

Suppose that our bookshelf application uses a content delivery network (CDN) to serve book covers. While this makes these images fast to download, it does mean that book covers need to be purged from the CDN when they change, in order for freshly updated images to take their place.

Images can be updated in one of two ways: the publisher of the book can sign in and upload a new image, or a Bookshelf staff member can use an admin interface to update an image on the publisher’s behalf.

In our bookshelf app, an Admin slice supports the latter functionality, and a Publisher slice the former. Both these slices want to trigger a CDN purge when a book cover is updated, but neither slice needs to know exactly how that’s achieved. Instead, a CDN slice can manage this operation.

  1. # slices/cdn/book_covers/purge.rb
  3. module CDN
  4.   module BookCovers
  5.     class Purge
  6.       def call(book_cover_path)
  7.         # "Purging logic here!"
  8.       end
  9.     end
  10.   end
  11. end

Slices can be configured by creating a file at config/slices/slice_name.rb.

To configure the Admin slice to import components from the CDN container (including the purge component above), we can create a config/slices/admin.rb file with the following configuration:

  1. # config/slices/admin.rb
  3. module Admin
  4.   class Slice < Hanami::Slice
  5.     import from: :cdn
  6.   end
  7. end

Let’s see this import in action in the console, where we can see that the Admin slices’ container now has a "cdn.book_covers.purge" component:

  1. bundle exec hanami console
  3. bookshelf[development]> Admin::Slice.boot.keys
  4. => ["settings",
  5.  "cdn.book_covers.purge",
  6.  "inflector",
  7.  "logger",
  8.  "notifications",
  9.  "rack.monitor",

Using the purge operation from the CDN slice within the Admin slice component below is now as simple as using the Deps mixin:

  1. # slices/admin/books/operations/update.rb
  4.   module Books
  5.     module Operations
  6.       class Update
  7.         include Deps[
  8.           "repositories.book_repo",
  9.           "cdn.book_covers.purge"
  10.         ]
  12.         def call(id, params)
  13.           # ... update the book using the book repository ...
  15.           # If the update is successful, purge the book cover from the CDN
  16.           purge.call(book.cover_path)
  17.         end
  18.       end
  19.     end
  20.   end
  21. end

It’s also possible to import only specific components from another slice. Here for example, the Publisher slice imports strictly the purge operation, while also - for reasons of its own choosing - using the suffix content_network instead of cdn:

  1. # config/slices/publisher.rb
  3. module Publisher
  4.   class Slice < Hanami::Slice
  5.     import keys: ["book_covers.purge"], from: :cdn, as: :content_network
  6.   end
  7. end

In action in the console:

Here, we configure the CDN slice to export only its purge component:

  1. # config/slices/cdn.rb
  2. module CDN
  3.   class Slice < Hanami::Slice
  4.     export ["book_covers.purge"]
  5.   end
  6. end

Slice settings

Every slice having automatic access to the app’s "settings" component is convenient, but for large apps this may lead to those settings becoming unwieldy: the list of settings can become long, and many settings will not be relevant to large portions of your app.

You can instead elect to define settings within specific slices. To do this, create a config/settings.rb within your slice directory.

  1. # slices/cdn/config/settings.rb
  3. module CDN
  4.   class Settings < Hanami::Settings
  5.     setting :cdn_api_key, Types::String
  6.   end
  7. end

With this in place, the "settings" component within your slice will be an instance of this slice-specific settings object.

  1. CDN_API_KEY=xyz bundle exec hanami console
  3. bookshelf[development]> CDN::Slice["settings"].cdn_api_key # => "xyz"

You can then include the slice settings via the Deps mixin within your slice.

  1. # slices/cdn/book_covers/purge.rb
  3. module CDN
  4.   module BookCovers
  5.     class Purge
  6.       include Deps["settings"]
  8.       def call(book_cover_path)
  9.         # use settings.cdn_api_key here
  10.       end
  11.     end
  12.   end
  13. end

Slice settings are loaded from environment variables just like the app settings, so take care to ensure you have no naming clashes between your slice and app settings.

See the for more information on settings.

Hanami will load all slices when your app boots. However, for certain workloads of your app, you may elect to load only a specified list of slices.

Loading specific slices brings the benefit of stronger code isolation, faster boot time and reduced memory usage. If your app had a background worker that processed jobs from one slice only, then it would make sense to load only that slice for the worker’s process.

To do this, set the HANAMI_SLICES environment variable with a comma-separated list of slice names.

    Setting this environment variable is a shortcut for setting config.slices in your app class.

    You may find the HANAMI_SLICES environment variable more convenient since it will not disturb slice loading for all other processes running your app.