EnvValidator

A lightweight Ruby gem that validates required environment variables at application boot time, providing type checking, format validation, and helpful error messages to prevent production disasters caused by missing or invalid configuration.

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add env_validator

If bundler is not being used to manage dependencies, install the gem by executing:

gem install env_validator

Quick Start

# config/initializers/env_validator.rb (Rails)
# or at top of main application file

EnvValidator.configure do
  # Required variables
  required :DATABASE_URL, type: :url
  required :SECRET_KEY_BASE, type: :string, min_length: 32
  required :RAILS_ENV, type: :string, in: %w[development test production]
  
  # Optional with defaults
  optional :PORT, type: :integer, default: 3000
  optional :LOG_LEVEL, type: :string, default: 'info', in: %w[debug info warn error]
  
  # Format validation
  required :STRIPE_API_KEY, format: /^sk_[a-zA-Z0-9]+$/
end

# Validate (call this after configuration)
EnvValidator.validate!

Features

✅ Required variable validation - Ensure critical env vars exist
✅ Type checking - String, Integer, Boolean, URL, Email, JSON, Base64, File/Dir paths
✅ Custom error messages - Clear indication of what's missing/wrong
✅ Simple DSL - Easy configuration syntax
✅ Boot-time validation - Fail early before app starts
✅ Optional variables with defaults - Handle optional configuration
✅ Format validation with regex - API keys, tokens, custom formats
✅ Constraints - Length limits, numeric ranges, inclusion lists
✅ Custom validators - User-defined validation logic

Built-in Types

type: :string      # Any string
type: :integer     # Numeric string that converts to integer
type: :float       # Numeric string that converts to float
type: :boolean     # 'true', 'false', '1', '0', 'yes', 'no', 'on', 'off'
type: :url         # Valid HTTP/HTTPS URL format
type: :email       # Valid email format
type: :json        # Valid JSON string
type: :base64      # Valid Base64 string
type: :file_path   # Existing file path
type: :dir_path    # Existing directory path

Usage Examples

Basic Validation

ENV['API_KEY'] = 'sk_test_123'
ENV['DEBUG'] = 'true'

EnvValidator.configure do
  required :API_KEY, type: :string
  required :DEBUG, type: :boolean
end

EnvValidator.validate! # Passes

Constraints and Defaults

EnvValidator.configure do
  required :SECRET, type: :string, min_length: 32
  optional :PORT, type: :integer, default: 3000, min: 1000, max: 9999
  required :ENV, type: :string, in: %w[development test production]
end

Custom Validation

EnvValidator.configure do
  required :CUSTOM_VALUE, type: :string do |value|
    value.start_with?('custom_') && value.length > 10
  end
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/[USERNAME]/env_validator.

License

The gem is available as open source under the terms of the MIT License.