{"id":15405139,"url":"https://github.com/fnando/superconfig","last_synced_at":"2025-10-12T02:01:54.939Z","repository":{"id":43044145,"uuid":"41358813","full_name":"fnando/superconfig","owner":"fnando","description":"Access environment variables. Also includes presence validation, type coercion and default values.","archived":false,"fork":false,"pushed_at":"2025-03-29T02:03:47.000Z","size":325,"stargazers_count":41,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T01:13:12.946Z","etag":null,"topics":["12-factor","config","configuration","configuration-management","dotenv","environment-variables","ruby"],"latest_commit_sha":null,"homepage":"","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/fnando.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["fnando"],"custom":["https://paypal.me/nandovieira/🍕"]}},"created_at":"2015-08-25T11:00:35.000Z","updated_at":"2025-03-29T02:03:50.000Z","dependencies_parsed_at":"2025-02-12T20:11:51.837Z","dependency_job_id":"2e09f141-965a-4898-a60b-4035bb0a4686","html_url":"https://github.com/fnando/superconfig","commit_stats":{"total_commits":56,"total_committers":4,"mean_commits":14.0,"dds":0.5,"last_synced_commit":"e7758357a287be736b92234148c23536b53e637f"},"previous_names":["fnando/env_vars"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fsuperconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fsuperconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fsuperconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fsuperconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fnando","download_url":"https://codeload.github.com/fnando/superconfig/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289434,"owners_count":20914464,"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":["12-factor","config","configuration","configuration-management","dotenv","environment-variables","ruby"],"created_at":"2024-10-01T16:15:10.542Z","updated_at":"2025-10-12T02:01:49.892Z","avatar_url":"https://github.com/fnando.png","language":"Ruby","readme":"![SuperConfig: Access environment variables. Also includes presence validation, type coercion and default values.](https://raw.githubusercontent.com/fnando/superconfig/main/superconfig.png)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/fnando/superconfig/actions/workflows/ruby-tests.yml\"\u003e\u003cimg src=\"https://github.com/fnando/superconfig/workflows/ruby-tests/badge.svg\" alt=\"Github Actions\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://rubygems.org/gems/superconfig\"\u003e\u003cimg src=\"https://img.shields.io/gem/v/superconfig.svg\" alt=\"Gem\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://rubygems.org/gems/superconfig\"\u003e\u003cimg src=\"https://img.shields.io/gem/dt/superconfig.svg\" alt=\"Gem\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"superconfig\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install superconfig\n\n## Usage\n\n```ruby\nConfig = SuperConfig.new do\n  mandatory :database_url, string\n  optional  :timeout, int, 10\n  optional  :force_ssl, bool, false\n  optional  :rails_env, \"development\", string, aliases: %w[env]\nend\n\nConfig.database_url\nConfig.timeout\nConfig.force_ssl?\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e Properties defined with `bool` will always be named as predicates, ending with\n\u003e `?`. The same thing happens if you define properties using `#set(name, value)`\n\u003e where the value is a boolean.\n\nYou can specify the description for both `mandatory` and `optional` methods;\nthis will be used in exceptions.\n\n```ruby\nConfig = SuperConfig.new do\n  mandatory :missing_var, string, description: \"this is important\"\nend\n\n#=\u003e SuperConfig::MissingEnvironmentVariable: MISSING_VAR (this is important) is not defined\n```\n\n### Using prefixed environment variables\n\nIf you're creating a library, you may want to use prefixed env vars. In this\ncase, you can pass a prefix to `SuperConfig.new`.\n\n```ruby\nConfig = SuperConfig.new(prefix: \"MYAPP\") do\n  optional :redis_url, string, \"redis://127.0.0.1\"\nend\n```\n\nThis will look for `MYAPP_REDIS_URL` in the environment variables.\n\n### Setting arbitrary properties\n\nIf you're going to use `SuperConfig` as your main configuration object, you can\nalso set arbitrary properties, like the following:\n\n```ruby\nConfig = SuperConfig.new do\n  optional :redis_url, string, \"redis://127.0.0.1\"\n  property :redis, -\u003e { Redis.new } # pass an object that responds to #call\n  property(:now) { Time.now }       # or pass a block.\nend\n\nConfig.redis.set(\"key\", \"value\")\nConfig.redis.get(\"key\")\n#=\u003e \"value\"\n```\n\n### Caching values\n\nValues are cached by default. If you want to dynamically generate new values,\nset `cache: false`.\n\n```ruby\nConfig = SuperConfig.new do\n  property(:uuid, cache: false) { SecureRandom.uuid }\nend\n```\n\n### Setting values\n\nYou can also set values using `SuperConfig#set`.\n\n```ruby\nConfig = SuperConfig.new do\n  set :domain, \"example.com\"\nend\n```\n\n### Troubleshooting\n\nYou may want to start a debug session without raising exceptions for missing\nvariables. In this case, just pass `raise_exception: false` instead to log error\nmessages to `$stderr`. This is especially great with Rails' credentials command\n(`rails credentials:edit`) when already defined the configuration.\n\n```ruby\nConfig = SuperConfig.new(raise_exception: false) do\n  mandatory :database_url, string, description: \"the leader database\"\nend\n\n#=\u003e [SUPERCONFIG] DATABASE_URL (the leader database) is not defined\n```\n\n### Rails credentials\n\nI like to centralize access to my Rails credentials; there's a handy mechanism\nfor doing that with `SuperConfig`:\n\n```ruby\nConfig = SuperConfig.new do\n  credential :api_secret_key\n  credential :slack_oauth_credentials do |creds|\n    SlackCredentials.new(creds)\n  end\nend\n\nConfig.api_secret_key\nConfig.slack_oauth_credentials\n#=\u003e The value stored under `Rails.application.credentials[:api_secret_key]`\n```\n\n### Types\n\nYou can coerce values to the following types:\n\n- `string`: Is the default. E.g. `optional :name, string`.\n- `int`: E.g. `optional :timeout, int`.\n- `float`: E.g. `optional :wait, float`.\n- `bigdecimal`: E.g. `optional :fee, bigdecimal`.\n- `bool`: E.g. `optional :force_ssl, bool`. Any of `yes`, `true` or `1` is\n  considered as `true`. Any other value will be coerced to `false`.\n- `symbol`: E.g. `optional :app_name, symbol`.\n- `array`: E.g. `optional :chars, array` or `optional :numbers, array(int)`. The\n  environment variable must be something like `a,b,c`.\n- `json`: E.g. `mandatory :keyring, json`. The environment variable must be\n  parseable by `JSON.parse(content)`.\n\n### Report\n\nSometimes it gets hard to understand what's set and what's not. In this case,\nyou can get a report by calling `SuperConfig::Base#report`. If you're using\nRails, you can create a rake task like this:\n\n```ruby\n# frozen_string_literal: true\n\ndesc \"Show SuperConfig report\"\ntask superconfig: [:environment] do\n  puts YourAppNamespace::Config.report\nend\n```\n\nThen, change your configuration so it doesn't raise an exception.\n\n```ruby\n# frozen_string_literal: true\n# file: config/config.rb\n\nmodule YourAppNamespace\n  Config = SuperConfig.new(raise_exception: false) do\n    mandatory :database_url, string\n    optional :app_name, string\n    optional :wait, string\n    optional :force_ssl, bool, true\n  end\nend\n```\n\nFinally, run the following command:\n\n```console\n$ rails superconfig\n❌ DATABASE_URL is not set (mandatory)\n✅ APP_NAME is set (optional)\n⚠️ WAIT is not set (optional)\n✅ FORCE_SSL is not set, but has default value (optional)\n```\n\n### Dotenv integration\n\nIf you're using [dotenv](https://rubygems.org/gems/dotenv), you can simply\nrequire `superconfig/dotenv`. This will load environment variables from\n`.env.local.%{environment}`, `.env.local`, `.env.%{environment}` and `.env`\nfiles, respectively. You _must_ add `dotenv` to your `Gemfile`.\n\n```ruby\nrequire \"superconfig/dotenv\"\n```\n\n### Configuring Rails\n\nIf you want to use `SuperConfig` even on your Rails configuration files like\n`database.yml` and `secrets.yml`, you must load it from `config/boot.rb`, right\nafter setting up Bundler.\n\n```ruby\nENV[\"BUNDLE_GEMFILE\"] ||= File.expand_path(\"../../Gemfile\", __FILE__)\n\n# Set up gems listed in the Gemfile.\nrequire \"bundler/setup\"\n\n# Load configuration.\nrequire \"superconfig/dotenv\"\nrequire File.expand_path(\"../config\", __FILE__)\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run\n`rake test` to run the tests. You can also run `bin/console` for an interactive\nprompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To\nrelease a new version, update the version number in `version.rb`, and then run\n`bundle exec rake release`, which will create a git tag for the version, push\ngit commits and tags, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/fnando/superconfig. This project is intended to be a safe,\nwelcoming space for collaboration, and contributors are expected to adhere to\nthe [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](http://opensource.org/licenses/MIT).\n\n## Icon\n\nIcon made by [eucalyp](https://www.flaticon.com/authors/eucalyp) from\n[Flaticon](https://www.flaticon.com/) is licensed by Creative Commons BY 3.0.\n","funding_links":["https://github.com/sponsors/fnando","https://paypal.me/nandovieira/🍕"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Fsuperconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnando%2Fsuperconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Fsuperconfig/lists"}