🔥 Nero
Nero is a RubyGem that offers declarative YAML-tags to simplify config files, e.g. for requiring and coercion of env-vars.
Additionally, it allows you to create your own.
Sample:
development:
# env-var with default value
secret: !env [SECRET, "dummy"]
# optional env-var with coercion
debug?: !env/bool? DEBUG
production:
# required env-var (only when getting the production-root)
secret: !env SECRET
# int coercion
max_threads: !env/integer [MAX_THREADS, 5]
# something custom
cache_ttl: !duration [2, hours]
Highlights
- 💎 declarative YAML-tags for e.g. requiring and coercing env-vars
- 🛠️ add custom tags
- 🛤️
Rails.application.config_for
stand-in - ♻️ Zeitwerk-only dependency
Installation
Install the gem and add to the application's Gemfile by executing:
bundle add nero
Usage
Warning
It's early days - the API and included tags will certainly change. Check the CHANGELOG when upgrading.
Given the following config:
# config/settings.yml
development:
# env-var with a fallback
secret: !env [SECRET, "dummy"]
# Though the default is false, explicitly providing "false"/"off"/"n"/"no" also works.
debug?: !env/bool? DEBUG
production:
# fail-fast on absence of SECRET
secret: !env SECRET
# always an integer
max_threads: !env/integer [MAX_THREADS, 5]
Loading this config:
# Loading development
Nero.load_config("config/settings", root: :development)
# ...and no ENV-vars were provided
#=> {secret: "dummy", debug?: false}
# ...with ENV {"debug" => "true"}
#=> {secret: "dummy", debug?: true}
# Loading production
Nero.load_config("config/settings", root: :production)
# ...and no ENV-vars were provided
# raises error: key not found: "SECRET" (KeyError)
# ...with ENV {"SECRET" => "s3cr3t", "MAX_THREADS" => "3"}
#=> {secret: "s3cr3t", max_threads: 3}
The following tags are provided:
-
!env KEY
,!env? KEY
Resp. to fetch or get a value fromENV
:--- # required secret: !env SECRET # optional, with fallback: secret: !env [SECRET, "dummy-fallback"] # ...or nil secret: !env? SECRET
- to coerce env-values:
-
env/integer
,env/integer?
:port: !env/integer [PORT, 3000] threads: !env/integer? THREADS # nil when not provided
-
env/bool
,env/bool?
:# required (valid values 'y(es)'/'n(o)', 'true'/'false', 'on'/'off') over18: !env/bool OVER18 # optional, with fallback: secure: !env/bool [SECURE, true] # ...or false: debug?: !env/bool? DEBUG
-
-
!path
Create a Pathname:config: !path config # combining tags: asset_folder: !path - !env PROJECT_ROOT - /public/assets
-
!uri
Create a URI:smtp_url: !uri - smtps:// - !env SMTP_CREDS - @smtp.gmail.com
-
!str/format
Using Ruby's format specifications:smtp_url: !str/format - smtps://%s:%s@smtp.gmail.com - !env SMTP_USER - !env SMTP_PASS # using references smtp_url: !str/format fmt: smtps://%<user>s:%<pass>s@smtp.gmail.com user: !env SMTP_USER pass: !env SMTP_PASS
Add one yourself:
Nero.configure do |nero|
nero.add_tag("foo") do |coder|
# coder.type is one of :scalar, :seq or :map
# e.g. respective YAML:
# ---
# !foo bar
# ---
# !foo
# - bar
# ---
# !foo
# bar: baz
#
# Find the value in the respective attribute, e.g. `coder.scalar`:
coder.scalar.upcase
end
# Other configuration options:
#
# `config_dir` (default: Pathname.pwd) - path used for expanding non-Pathnames passed to `load_config`, e.g.
# `Nero.load_config(:app)` loads file `Pathname.pwd / "app.yml"`.
nero.config_dir = Rails.root / "config"
end
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
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 the created tag, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/eval/nero.
License
The gem is available as open source under the terms of the MIT License.