configuration_skill

Overview

This skill explains how to use Effect's configuration system to load, validate, and manage application settings. It covers environment and JSON providers, type-safe config primitives, nested structures, defaults, and handling sensitive values. You'll get practical patterns for composing configs and integrating them into Effects and Layers.

How this skill works

Effect exposes Config primitives (Config.string, Config.number, Config.boolean, Config.secret, Config.redacted, etc.) that read values from configurable providers like the environment, JSON objects, or Maps. Config combinators (Config.all, Config.nested, Config.withDefault, Config.option, Config.mapOrFail) let you build typed configurations, validate values with Schema, and transform or provide fallbacks. Providers are pluggable so you can swap environment input for JSON or test maps and supply a provider via Layers.

When to use it

• When you need type-safe reading of environment variables or JSON-based config.
• When configuration values require validation or conversion (e.g., port number ranges).
• When secrets must be protected from accidental logs (use redacted/secret).
• When grouping related settings into nested structures for clarity.
• When writing tests and you need deterministic config via mock providers.

Best practices

• Apply Config.withDefault for optional or safe fallback values to avoid runtime failures.
• Use Config.redacted or Config.secret for any sensitive values to prevent accidental logging.
• Group related keys with Config.nested and Config.all to keep a clear config shape.
• Validate complex values with Effect Schema and mapOrFail to surface errors at startup.
• Provide test-specific providers (ConfigProvider.fromMap/fromJson) for deterministic tests.

Example use cases

• Loading a database block with Config.nested('DB') and defaults for max connections.
• Reading numeric ports with Schema validation to ensure 1–65535 and fail fast on bad input.
• Swapping the default environment provider for a JSON provider in integration tests.
• Combining primary and fallback keys using Config.orElse to support multiple deploy patterns.
• Protecting API keys with Config.redacted so logs show <redacted> while code can access the real value when needed.