{"id":14955258,"url":"https://github.com/maxim/loadout","last_synced_at":"2025-09-11T02:39:58.393Z","repository":{"id":252606719,"uuid":"840922568","full_name":"maxim/loadout","owner":"maxim","description":"Rails configuration helpers","archived":false,"fork":false,"pushed_at":"2024-08-14T03:24:31.000Z","size":35,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-29T08:41:38.054Z","etag":null,"topics":["config","configuration","credentials","dry","env","environment","environment-variables","fail-fast","rails","secrets"],"latest_commit_sha":null,"homepage":"https://github.com/maxim/loadout","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-11T05:20:34.000Z","updated_at":"2024-11-24T06:10:39.000Z","dependencies_parsed_at":"2024-08-14T04:43:15.513Z","dependency_job_id":null,"html_url":"https://github.com/maxim/loadout","commit_stats":null,"previous_names":["maxim/loadout"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxim%2Floadout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxim%2Floadout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxim%2Floadout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxim%2Floadout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxim","download_url":"https://codeload.github.com/maxim/loadout/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237126440,"owners_count":19259473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["config","configuration","credentials","dry","env","environment","environment-variables","fail-fast","rails","secrets"],"created_at":"2024-09-24T13:10:46.490Z","updated_at":"2025-02-09T09:31:30.989Z","avatar_url":"https://github.com/maxim.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Loadout\n\nRails vanilla config is good enough, but tends to get messy. This gem provides a few helpers to\n\n- Reduce repetition\n- Raise a helpful error when required values are not set\n- Parse reasonable ENV values representing bools, ints, floats, and lists\n- Raise a helpful error when an ENV value appears to be unreasonable/unintentional\n\nYou get these composable helpers:\n\n- `cred`\n- `env`\n- `prefix`\n- `bool`\n- `int`\n- `float`\n- `list`\n\n## Synopsis\n\n```ruby\nRails.application.configure do\n  extend Loadout::Helpers\n\n  config.some_secret = cred(:secret) { 'default' }\n  config.value_from_env_or_cred = env.cred(:key_name)\n\n  prefix(:service) do\n    config.x.service.optional_value = env.cred(:api_key) { 'default' }\n    config.x.service.required_value = env.cred(:api_secret)\n    config.x.service.optional_bool  = bool.env(:bool_flag) { false }\n    config.x.service.optional_int   = int.env.cred(:some_int) { nil }\n    config.x.service.required_float = float.env.cred(:some_float)\n    config.x.service.required_array = list.env(:comma_list)\n  end\nend\n```\n\n## Installation\n\nNote: this gem requires Ruby 3.\n\nInstall the gem and add to the application's Gemfile by executing:\n\n    $ bundle add loadout\n\nIf bundler is not being used to manage dependencies, install the gem by executing:\n\n    $ gem install loadout\n\n## Usage\n\n1. Include helpers into your `config/environments/*.rb`:\n\n    ```ruby\n    extend Loadout::Helpers\n    ```\n\n    This should be done in each file where you'd like to use loadout.\n\n2. Grab a value from credentials:\n\n    ```ruby\n    config.key = cred(:key_name)\n    ```\n\n    If you don't set this credential, you will get an error:\n\n    ```\n    Loadout::MissingConfigError: required credential (key_name) is not set\n    ```\n\n3. Or from ENV:\n\n    ```\n    config.key = env(:key_name)\n    ```\n\n    If you don't set this env, you will get an error:\n\n    ```\n    Loadout::MissingConfigError: required environment variable (KEY_NAME) is not set\n    ```\n\n4. Look up ENV, then credentials, then fail:\n\n    ```ruby\n    config.key = env.cred(:key_name)\n    ```\n\n    If neither are set, you will get an error:\n\n    ```\n    Loadout::MissingConfigError: required environment variable (KEY_NAME) or credential (key_name) is not set\n    ```\n\n5. Or the other way around:\n\n    ```ruby\n    config.key = cred.env(:key_name)\n    ```\n\n6. If it's a nested credential value, you can supply multiple keys:\n\n    ```ruby\n    # Look up service.key_name in credentials\n    config.key = cred(:service, :key_name)\n    ```\n\n7. It will do the right thing if you also add env:\n\n    ```ruby\n    # Look up service.key_name in credentials, or SERVICE_KEY_NAME in ENV\n    config.key = cred.env(:service, :key_name)\n    ```\n\n8. Parse ENV value into a boolean:\n\n    ```ruby\n    # Valid true strings: 1/y/yes/t/true\n    # Valid false strings: \"\" or 0/n/no/f/false\n    # (case insensitive)\n    #\n    # Any other string will raise an error.\n    config.some_flag = bool.cred.env(:key_name)\n    ```\n\n    If you set an invalid value, you will get an error:\n\n    ```\n    Loadout::InvalidConfigError: invalid value for bool (`value`) in KEY_NAME\n    ```\n\n    Note: because credentials come from YAML, they don't need to be parsed. Only ENV values are parsed.\n\n9. Integers and floats are also supported:\n\n    ```ruby\n    config.some_int   = int.cred.env(:int_key_name)\n    config.some_float = float.cred.env(:float_key_name)\n    ```\n\n10. Lists are supported too:\n\n    ```ruby\n    # Parses strings like \"foo, bar, baz\", \"foo|bar|baz\", \"foo bar baz\" into ['foo', 'bar', 'baz']\n    config.some_list = list.cred.env(:key_name)\n    ```\n\n11. You can set your own list separator (string or regex):\n\n    ```ruby\n    # Parses 'foo0bar0baz' into ['foo', 'bar', 'baz']\n    config.some_list = list('0').env(:key_name)\n    ```\n\n12. Use a block at the end to specify a default value:\n\n    ```ruby\n    config.some_list = list.cred.env(:key_name) { ['default'] }\n    ```\n\n13. Use prefix to avoid repeating the same nesting:\n\n    ```ruby\n    prefix(:service) do\n      config.x.service.api_key    = env(:api_key)    # Looks up \"SERVICE_API_KEY\"\n      config.x.service.api_secret = env(:api_secret) # Looks up \"SERVICE_API_SECRET\"\n    end\n    ```\n\n    Note that left hand side is unaffected. Only loadout helpers get auto-prefixed.\n\n14. `prefix` lets you supply a default to the whole block:\n\n    ```ruby\n    prefix(:service, default: -\u003e { 'SECRET' }) do\n      config.x.service.api_key    = env(:api_key)    # falls back to 'SECRET'\n      config.x.service.api_secret = env(:api_secret) # falls back to 'SECRET'\n    end\n    ```\n\n## Advanced configuration\n\n### I don't like all these helpers polluting my config!\n\nInstead of `extend Loadout::Helpers` you can `extend Loadout` to include one proxy method `loadout`. Now all helpers live in one place.\n\n```ruby\nRails.application.configure do\n  extend Loadout\n\n  config.some_key = loadout.cred.env(:some_key)\nend\n```\n\nFeel free to alias it to something shorter if you'd like:\n\n```ruby\nRails.application.configure do\n  extend Loadout\n  alias l loadout\n\n  config.some_key = l.cred.env(:some_key)\nend\n```\n\n### Credentials and ENV\n\nBy default loadout will look into `credentials` and `ENV` in your config's context. If your credentials are called something else, or you want to supply an alternative source of ENV, you can configure it like so:\n\n```ruby\nRails.application.configure do\n  extend Loadout::Helpers\n  loadout creds: alt_credentials, env: alt_env\n\n  # Now loadout will use alt_credentials and alt_env to look up values.\nend\n```\n\n## Tips and Tricks\n\n### What should I put in `application.rb`?\n\nAll your environments load `application.rb` as their dependency. That's why you should not put any hard requirements (`env` or `cred`) into application.rb. It would make all dependent environments crash unless every single env and cred is provided. And you will not be able to override these requirements, because ruby parses application.rb first.\n\n```ruby\n# application.rb\nconfig.some_secret = env(:some_secret)\n```\n\n```ruby\n# test.rb (BAD, DOESN'T WORK)\nconfig.some_secret = cred(:some_secret) { 'secret' } # \u003c= ruby will not get here\n```\n\nRuby will never get to test.rb, because application.rb will crash when it can't find `ENV['SOME_SECRET']`.\n\nMy recommended approach is to put only defaults and nils in your application.rb. Assign only literal values so that you have a comprehensive list of every supported configuration in one place. Then you can add stricter requirements (via helpers like `env` and `cred`) to your actual environment files.\n\n```ruby\n# application.rb\nconfig.some_secret = 'default'\n```\n\n```ruby\n# development.rb\nconfig.some_secret = cred(:some_secret)\n```\n\n```ruby\n# test.rb (cred for VCR recording, default otherwise)\nconfig.some_secret = cred(:some_secret) { 'secret' }\n```\n\n```ruby\n# production.rb\nconfig.some_secret = env(:some_secret)\n```\n\nThis will work.\n\n\n### What if one environment depends on another?\n\nIf you have [dependencies between environment files](https://signalvnoise.com/posts/3535-beyond-the-default-rails-environments), for example your staging.rb depends on your production.rb, and has relaxed requirements compared to production, here's a trick you can use.\n\n```ruby\n# production.rb\nconfig.some_secret = env(:some_secret) if Rails.env.production?\n```\n\n```ruby\n# staging.rb\nconfig.some_secret = env(:some_secret) { 'default' }\n```\n\nNote the condition in production.rb. Now you are requriing `ENV['SOME_SECRET']` in production, while allowing a default in staging.\n\n\n### Cleaning up nested settings\n\nHere are some examples on how you can make nested config settings look neat.\n\n**Use `tap` for literals**\n\n```ruby\nconfig.x.service.tap do |service|\n  service.api_key    = 'key'\n  service.api_secret = 'secret'\n  service.api_url    = 'https://api.example.com'\nend\n```\n\n**Use local variable with `prefix`**\n\n```ruby\nprefix(:service) do\n  service            = config.x.service\n  service.api_key    = env(:api_key)\n  service.api_secret = env(:api_secret)\n  service.api_url    = env(:api_url)\nend\n```\n\n**Use `OrderedOptions` with `prefix`**\n\nBe careful, this overwrites the whole service config.\n\n```ruby\nconfig.x.service = prefix(:service) do\n  ActiveSupport::OrderedOptions[\n    api_key:    env(:api_key),\n    api_secret: env(:api_secret),\n    api_url:    env(:api_url)\n  ]\nend\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/maxim/loadout. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/maxim/loadout/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Loadout project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/maxim/loadout/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxim%2Floadout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxim%2Floadout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxim%2Floadout/lists"}