Configuring Hanami Providers

Set up providers for services, databases, and application components following Hanami conventions.

Quick Reference

• Location: config/providers/<name>.rb
• Structure: Hanami.app.register_provider(:name) do ... end
• Lifecycle: prepare (lazy) → start (eager, on first use or boot)
• Rule: Every external service gets a provider. Settings go through target["settings"].

HARD-GATE

DO NOT hardcode credentials, URLs, or API keys in providers.
DO NOT call the container directly outside of providers.
DO use settings for all environment-dependent configuration.

Core Process

1. Identify the dependency — external service, database, or application component.
2. Define settings in config/settings.rb if the service needs configuration:

   setting :redis_url, constructor: Types::String

3. Create the provider at config/providers/<name>.rb:

   Hanami.app.register_provider(:redis) do
     prepare do
       require "redis"
     end
   
     start do
       url = target["settings"].redis_url
       client = Redis.new(url:)
       register("redis", client)
     end
   end

4. Use prepare for requiring gems and lightweight setup.
5. Use start for instantiation and registration. Access other registered components via target[...].
6. Register with a descriptive key — "redis", "http_client", not generic names.
7. Verify — ensure the provider boots without errors. If it needs external resources (database, API), handle connection failures gracefully.

Common Provider Patterns

Apply these patterns for frequently encountered service types:

• ROM/database connection — register the ROM container in start; use target["settings"] for the database URL; depend on the :persistence provider in consumers.
• HTTP client — require the HTTP library in prepare; instantiate with base URL and headers from settings in start; register as "http_client" or a service-specific key.
• Background job adapter — configure the adapter class and queue connection in start; register as "jobs.adapter" so job classes can resolve it via Deps.
• Cache store — require the cache library in prepare; build the store with TTL and connection settings from target["settings"] in start.

For extended code examples, see PROVIDER_PATTERNS.md.

Output Style

1. Provider file — the complete config/providers/<name>.rb content.
2. Settings additions — any new settings needed in config/settings.rb.
3. Registration key — the key used to register the component.
4. Injection usage — how to use include Deps["<key>"] in consumers.
5. Verification — how to confirm the provider boots correctly.
6. English only unless user requests otherwise.

Integration