https://github.com/16/envv
Ruby environment variables with schema validation and coercion.
https://github.com/16/envv
coercion dry-rb env environment-variables ruby ruby-gem schema-validation
Last synced: 5 months ago
JSON representation
Ruby environment variables with schema validation and coercion.
- Host: GitHub
- URL: https://github.com/16/envv
- Owner: 16
- License: mit
- Created: 2023-08-30T16:58:49.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-16T07:31:47.000Z (8 months ago)
- Last Synced: 2025-12-01T07:14:45.080Z (7 months ago)
- Topics: coercion, dry-rb, env, environment-variables, ruby, ruby-gem, schema-validation
- Language: Ruby
- Homepage:
- Size: 44.9 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://badge.fury.io/rb/envv)
# ENVV
ENVV provides a ENV like accessor with schema validation and coerced values.
* By providing an explicit schema of required environments variables, it will facilitate collaborative development and deployment.
* It will inform you during the boot process of your application if you miss to provide some valid environment variables, avoiding bugs during execution.
* Schema and coercition are handled by [dry-rb](https://dry-rb.org/) libraries, with the benefits of the powerful DSL of [Dry::Schema](https://dry-rb.org/gems/dry-schema), its built-in [predicates](https://dry-rb.org/gems/dry-schema/1.13/basics/built-in-predicates/) and [types](https://dry-rb.org/gems/dry-schema/1.13/basics/type-specs/).
## Installation
Install the gem and add to the application's Gemfile by executing:
$ bundle add envv
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install envv
**Requirements**: this library officially supports the following Ruby versions
* MRI `>= 3.0.0`
## Usage
Build your ENVV with [Dry::Schema.Params](https://dry-rb.org/gems/dry-schema/1.13/params/) rules to describe your env vars requirements.
```ruby
ENVV.build! do
required(:MY_STRING_VAR).filled(:string)
required(:MY_INT_VAR).filled(:integer, gt?: 3000)
required(:MY_BOOLEAN_VAR).filled(:bool)
end
```
If requirements are not satisfied, it will **raise an exception**. So be sure this validation occurs as soon as possible in the boot process of your application.
In a Ruby On Rails application, you can place it in an initializer and ensure it will be executed first by naming it `config/initializers/01-envv.rb` for example, since initializers are run in alphabetical order.
If environment variables are validated, you can now access their coerced value with `ENVV#fetch` method:
```ruby
# With ENV
#
# MY_STRING_VAR=hello
# MY_INT_VAR=4000
# MY_BOOLEAN_VAR=True
ENVV.fetch("MY_STRING_VAR") # ⇒ "Hello"
ENVV.fetch("MY_INT_VAR") # ⇒ 4000
ENVV.fetch("MY_BOOLEAN_VAR") # ⇒ true
```
### Adding extra features with your own ENVV wrapper
You can include [ENVV::Base](lib/envv/base.rb) in your own class or module and thus provide extra features.
With a module
```ruby
module MyAppEnv
extend ENVV::Base
def is_dark?
fetch("IS_DARK")
end
end
MyAppEnv.build! do
required(:IS_DARK).filled(:bool)
end
# IS_DARK=True
MyAppEnv.is_dark? # => true
```
With a class
```ruby
class MyAppEnv
include ENVV::Base
def [](key)
fetch(key)
end
end
e = MyAppEnv.new.build! do
required(:IS_DARK).filled(:bool)
end
e["IS_DARK"] # => true
```
Be creative !
## 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 the created tag, 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/16/envv. 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/16/envv/blob/master/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). See the separate [LICENSE.txt](LICENSE.txt) file. © Copyright 2023 Fabrice Luraine aka asciilander with spacedotspace collective.