Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fnando/superconfig
Access environment variables. Also includes presence validation, type coercion and default values.
https://github.com/fnando/superconfig
12-factor config configuration configuration-management dotenv environment-variables ruby
Last synced: 12 days ago
JSON representation
Access environment variables. Also includes presence validation, type coercion and default values.
- Host: GitHub
- URL: https://github.com/fnando/superconfig
- Owner: fnando
- License: mit
- Created: 2015-08-25T11:00:35.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2024-10-27T01:33:11.000Z (17 days ago)
- Last Synced: 2024-10-27T02:32:04.515Z (17 days ago)
- Topics: 12-factor, config, configuration, configuration-management, dotenv, environment-variables, ruby
- Language: Ruby
- Homepage:
- Size: 311 KB
- Stars: 40
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
## Installation
Add this line to your application's Gemfile:
```ruby
gem "superconfig"
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install superconfig
## Usage
```ruby
Config = SuperConfig.new do
mandatory :database_url, string
optional :timeout, int, 10
optional :force_ssl, bool, false
optional :rails_env, "development", string, aliases: %w[env]
end
Config.database_url
Config.timeout
Config.force_ssl?
```
You can specify the description for both `mandatory` and `optional` methods;
this will be used in exceptions.
```ruby
Config = SuperConfig.new do
mandatory :missing_var, string, description: "this is important"
end
#=> SuperConfig::MissingEnvironmentVariable: MISSING_VAR (this is important) is not defined
```
If you're going to use `SuperConfig` as your main configuration object, you can
also set arbitrary properties, like the following:
```ruby
Config = SuperConfig.new do
optional :redis_url, string, "redis://127.0.0.1"
property :redis, -> { Redis.new } # pass an object that responds to #call
property(:now) { Time.now } # or pass a block.
end
Config.redis.set("key", "value")
Config.redis.get("key")
#=> "value"
```
Values are cached by default. If you want to dynamically generate new values,
set `cache: false`.
```ruby
Config = SuperConfig.new do
property(:uuid, cache: false) { SecureRandom.uuid }
end
```
You may want to start a debug session without raising exceptions for missing
variables. In this case, just pass `raise_exception: false` instead to log error
messages to `$stderr`. This is especially great with Rails' credentials command
(`rails credentials:edit`) when already defined the configuration.
```ruby
Config = SuperConfig.new(raise_exception: false) do
mandatory :database_url, string, description: "the leader database"
end
#=> [SUPERCONFIG] DATABASE_URL (the leader database) is not defined
```
I'd like to centralize access to my credentials; there's a handy mechanism for
doing that with `SuperConfig`:
```ruby
Config = SuperConfig.new do
credential :api_secret_key
credential :slack_oauth_credentials do |creds|
SlackCredentials.new(creds)
end
end
Config.api_secret_key
Config.slack_oauth_credentials
#=> The value stored under `Rails.application.credentials[:api_secret_key]`
```
### Types
You can coerce values to the following types:
- `string`: Is the default. E.g. `optional :name, string`.
- `int`: E.g. `optional :timeout, int`.
- `float`: E.g. `optional :wait, float`.
- `bigdecimal`: E.g. `optional :fee, bigdecimal`.
- `bool`: E.g. `optional :force_ssl, bool`. Any of `yes`, `true` or `1` is
considered as `true`. Any other value will be coerced to `false`.
- `symbol`: E.g. `optional :app_name, symbol`.
- `array`: E.g. `optional :chars, array` or `optional :numbers, array(int)`. The
environment variable must be something like `a,b,c`.
- `json`: E.g. `mandatory :keyring, json`. The environment variable must be
parseable by `JSON.parse(content)`.
### Report
Sometimes it gets hard to understand what's set and what's not. In this case,
you can get a report by calling `SuperConfig::Base#report`. If you're using
Rails, you can create a rake task like this:
```ruby
# frozen_string_literal: true
desc "Show SuperConfig report"
task superconfig: [:environment] do
puts YourAppNamespace::Config.report
end
```
Then, change your configuration so it doesn't raise an exception.
```ruby
# frozen_string_literal: true
# file: config/config.rb
module YourAppNamespace
Config = SuperConfig.new(raise_exception: false) do
mandatory :database_url, string
optional :app_name, string
optional :wait, string
optional :force_ssl, bool, true
end
end
```
Finally, run the following command:
```console
$ rails superconfig
❌ DATABASE_URL is not set (mandatory)
✅ APP_NAME is set (optional)
⚠️ WAIT is not set (optional)
✅ FORCE_SSL is not set, but has default value (optional)
```
### Dotenv integration
If you're using [dotenv](https://rubygems.org/gems/dotenv), you can simply
require `superconfig/dotenv`. This will load environment variables from
`.env.local.%{environment}`, `.env.local`, `.env.%{environment}` and `.env`
files, respectively. You _must_ add `dotenv` to your `Gemfile`.
```ruby
require "superconfig/dotenv"
```
### Configuring Rails
If you want to use `SuperConfig` even on your Rails configuration files like
`database.yml` and `secrets.yml`, you must load it from `config/boot.rb`, right
after setting up Bundler.
```ruby
ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
# Set up gems listed in the Gemfile.
require "bundler/setup"
# Load configuration.
require "superconfig/dotenv"
require File.expand_path("../config", __FILE__)
```
## Development
After 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.
To 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 tags, and push the `.gem` file to
[rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at
https://github.com/fnando/superconfig. This project is intended to be a safe,
welcoming space for collaboration, and contributors are expected to adhere to
the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
## License
The gem is available as open source under the terms of the
[MIT License](http://opensource.org/licenses/MIT).
## Icon
Icon made by [eucalyp](https://www.flaticon.com/authors/eucalyp) from
[Flaticon](https://www.flaticon.com/) is licensed by Creative Commons BY 3.0.