Manage Settings

manage-settings

Use this skill when managing Hanami 2.x application settings.

Core principle: Settings are typed, validated, and loaded from environment variables. They are the single source of truth for configuration.

Quick Reference

Workflow: Define → Configure → Access → Verify

1. Define settings in config/settings.rb

# config/settings.rb
# frozen_string_literal: true

module MyApp
  class Settings < Hanami::Settings
    setting :database_url, constructor: Types::String
    setting :port, default: 2300, constructor: Types::Integer
    setting :host, default: "localhost", constructor: Types::String
    setting :session_secret, constructor: Types::String
    setting :api_key, constructor: Types::String.optional
    setting :log_level, default: "info", constructor: Types::String.enum("debug", "info", "warn", "error")
  end
end

2. Set environment variables (UPPER_SNAKE_CASE)

Use .env files for local development (supported via the dotenv gem).

3. Access settings in components

# In an Action
Hanami.app[:settings].database_url

# In a provider
target[:settings].session_secret

# In a service object (injected)
include Deps["settings"]
settings.database_url

4. Verify settings load correctly

Boot the app with hanami server or bundle exec hanami console to confirm all required settings are present and correctly typed. Required settings (no default:) raise immediately at boot if the corresponding environment variable is missing — this is the intended failure mode.

# Quick console check
bundle exec hanami console
Hanami.app[:settings].inspect

Slice-level settings override or extend app settings:

# slices/api/config/slice.rb
class Slice < Hanami::Slice
  config.settings do
    setting :api_key, constructor: Types::String
  end
end

Integration