Documentation

Strict Adapter

Catch typos and missing feature flags early by raising errors or warnings when an unknown feature is checked.

The strict adapter wraps another adapter and ensures that a feature exists before allowing it to be checked. This helps you catch typos and missing feature flags early instead of silently returning false for features that don't exist.

Installation

This adapter is included with the flipper gem.

Usage

Rails Configuration

The easiest way to enable strict mode in a Rails app is through configuration:

# config/initializers/flipper.rb
Rails.application.configure do
  # Raise an error for unknown features
  config.flipper.strict = :raise

  # Or just log a warning
  config.flipper.strict = :warn
end

You can also use an environment variable:

FLIPPER_STRICT=warn
# or
FLIPPER_STRICT=raise

By default, strict mode is disabled in production and set to :warn in development and test.

Manual Configuration

require 'flipper/adapters/strict'

Flipper.configure do |config|
  config.use Flipper::Adapters::Strict, :raise
end

Handler Options

The second argument controls what happens when an unknown feature is checked:

• :raise or true — Raises a Flipper::Adapters::Strict::NotFound error.
• :warn — Logs a warning to stderr.
• :noop, false, or nil — Silently ignores missing features (effectively disabling strict mode).
• Block — Calls a custom block with the unknown feature, useful for custom logging or telemetry.

# Raise on missing features
Flipper.configure do |config|
  config.use Flipper::Adapters::Strict, :raise
end

# Warn on missing features
Flipper.configure do |config|
  config.use Flipper::Adapters::Strict, :warn
end

# Custom handler
Flipper.configure do |config|
  config.use Flipper::Adapters::Strict do |feature|
    MyLogger.warn("Unknown feature flag checked: #{feature.key}")
  end
end

Example

# Without strict mode, typos silently return false:
Flipper.enable(:search)
Flipper.enabled?(:serach) # => false (typo, but no error!)

# With strict mode (:raise), you get an error immediately:
Flipper.enabled?(:serach)
# => Flipper::Adapters::Strict::NotFound:
#    Could not find feature :serach.
#    Call `Flipper.add(:serach)` to create it.

Recommended Setup

We recommend enabling strict mode in development and test so you catch issues early, while leaving it disabled in production to avoid unexpected errors:

Rails.application.configure do
  config.flipper.strict = Rails.env.local? && :warn
end