For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Configuration is a supplied, validated dependency

A service is a named interface. A Layer describes how to build it and supply its dependencies. Schema defines accepted values and checks data at runtime.¶

Read configuration when its Layer builds. Expose parsed values through a service rather than reading environment variables throughout domain code.¶

Define accepted values before reading them

Config.Literals limits APP_ENV to three values. The declared default handles a missing setting.¶

import { Config } from "effect";

import { ConfigService } from "./config-service.js";

export class AppConfig extends ConfigService.Service<AppConfig>()(
  "@rat-stack/core/AppConfig",
  {
    appEnv: Config.Literals(
      ["development", "test", "production"],
      "APP_ENV"
    ).pipe(Config.withDefault("development")),
  }
) {}

The environment name and accepted values live together. The default does not make an invalid supplied value acceptable.¶

Effect’s Config.schema can describe more complex validated settings. Use the Schema-backed path instead of writing a second parser for the same domain rule.¶

Supply another configuration source

A ConfigProvider supplies raw configuration inputs. Tests can replace the source with fromUnknown while still exercising the production parsing Layer.¶

const withProvider = (root: Parameters<typeof ConfigProvider.fromUnknown>[0]) =>
  Layer.provide(
    AppConfig.layer,
    ConfigProvider.layer(ConfigProvider.fromUnknown(root))
  );

it.effect("reads APP_ENV through the active ConfigProvider", () =>
  Effect.gen(function* readsFromProvider() {
    const config = yield* AppConfig;
    expect(config.appEnv).toBe("test");
  }).pipe(Effect.provide(withProvider({ APP_ENV: "test" })))
);

The suite also checks rejection:¶

it.effect("rejects values outside the literal set", () =>
  Effect.gen(function* rejectsUnknownLiteral() {
    const error = yield* Effect.flip(
      Layer.build(withProvider({ APP_ENV: "staging" }))
    );

    expect(error._tag).toBe("ConfigError");
  })
);

Supply typed values when parsing is not the task

AppConfig.configLayer accepts already-typed values. It uses Layer.succeed and skips parsing. Use this for a test about domain behavior. Use a provider when the test is about configuration decoding.¶

rat-stack’s factory provides these two ways to supply configuration.¶

Common wrong approach

Reading process.env inside each domain method ties the method to the host and allows inconsistent parsing. A config service moves that choice to construction and gives tests a service they can replace.¶

Keep missing settings and rejected settings distinct. Let construction fail when a supplied value violates the schema.¶

Effect idiom and house rule

• Config parses supplied data and reports typed failures³⁶. ConfigProvider selects the source.¶
• In rat-stack, declare environment inputs in .env.schema. Alchemy provider credentials come from profiles. Do not supply them through environment variables.¶
• Do not unwrap a redacted value for logs or public examples.¶

See also: services¹⁶, Layer composition¹³, failures³⁶, and tests²².¶

Read why dependency injection matters¹⁴.¶

Last changed 2026-10-07 in e73c9d9. Source on GitHub. Change log.