25 - Config: Type-Safe Configuration

Previous · Next

Config is a typed description of how to read configuration values. Like Effect, a Config does nothing until it is interpreted by a ConfigProvider.

The default provider reads process.env; tests swap in a Map. Business logic does not change.

What you’ll work through

index.test.ts contains four beats: primitive readers (Config.string, Config.number, etc.), Config.redacted and Config.withDefault, swapping the default provider for a test Map, and exposing the resolved config as a service so business code yields it like any other dependency.

By the end you should treat config as a service like any other — the boundary between environment and code is one Layer.

The Boundary

1
       reads from
2
Config<A>  ◄────────  ConfigProvider
3
   │
4
   ├── process.env                          (production default)
5
   ├── ConfigProvider.fromUnknown(...)          (tests)
6
   └── ConfigProvider.fromJson(...)         (file-based)

A Config<A> is interpreted at the boundary of the program. Within the program, every value is fully typed, no string | undefined, no manual coercion.

`Config.string`, `integer`, `number`, `boolean`

Creates a typed Config that reads a single environment variable. Parses the string into the target type and fails with a ConfigError if the value is missing or malformed.

1
import { Config } from "effect"
2

3
//      ┌─── Config<string>
4
//      ▼
5
const host = Config.string("HOST")
6

7
//      ┌─── Config<number>
8
//      ▼
9
const port = Config.int("PORT")
10

11
//      ┌─── Config<boolean>
12
//      ▼
13
const debug = Config.boolean("DEBUG")

When to Use

For each environment variable that has a known type. Config.int accepts only valid integers; Config.boolean accepts "true", "false", "1", "0".

`Config.redacted`

Creates a Config<Redacted<string>> for secrets. The Redacted wrapper hides the value from logs, stack traces, and toString calls.

Extract the raw value with Redacted.value only at the point of use.

1
import { Config, Redacted } from "effect"
2

3
const program = Effect.gen(function* () {
4
  //      ┌─── Redacted<string>
5
  //      ▼
6
  const apiKey = yield* Config.redacted("API_KEY")
7

8
  // Logging this is safe, prints "<redacted>".
9
  console.log(apiKey)
10

11
  // Extract only when calling the API.
12
  fetch(url, { headers: { Authorization: Redacted.value(apiKey) } })
13
})

`Config.withDefault`

Returns a Config that falls back to a constant when the underlying value is missing.

1
//      ┌─── Config<number>
2
//      ▼
3
const port = Config.int("PORT").pipe(Config.withDefault(3000))

Details

Config.withDefault only fires when the value is absent. A present but malformed value (e.g. PORT=banana) still produces a ConfigError.

The signature widens the success type to A | A2, but TypeScript flattens it when the default matches.

When to Use

For optional settings. Prefer withDefault over Config.orElse(() => Config.succeed(...)) because it is the dedicated combinator for constant fallbacks.

Reach for Config.orElse only when the fallback is itself a Config (e.g. another environment variable).

`Config.all`

Reads multiple configs at once and assembles them into a record.

1
//      ┌─── Config<{ host: string; port: number }>
2
//      ▼
3
const server = Config.all({
4
  host: Config.string("HOST"),
5
  port: Config.int("PORT").pipe(Config.withDefault(3000)),
6
})

`Effect.provideService` for Tests

Swap the default provider for a deterministic map. Nothing touches process.env.

1
import { ConfigProvider, Effect } from "effect"
2

3
const testProvider = ConfigProvider.fromUnknown(
4
  new Map([
5
    ["PORT", "4000"],
6
    ["HOST", "localhost"],
7
  ]),
8
)
9

10
const result = yield* program.pipe(Effect.provideService(testProvider))

Config as a Service

Wrapping Config inside a Layer is the recommended production pattern. Business logic depends on the service tag, never on Config directly, so tests do not need to set up a ConfigProvider at all.

1
import { Context, Effect, Layer, Config, Redacted } from "effect"
2

3
class AppConfig extends Context.Service("AppConfig")<
4
  AppConfig,
5
  { readonly port: number; readonly apiKey: string }
6
>() {
7
  // Reads from the ambient ConfigProvider (process.env by default).
8
  static readonly layer = Layer.effect(
9
    AppConfig,
10
    Effect.gen(function* () {
11
      const port = yield* Config.int("PORT").pipe(Config.withDefault(3000))
12
      const apiKey = yield* Config.redacted("API_KEY")
13
      return { port, apiKey: Redacted.value(apiKey) }
14
    }),
15
  )
16

17
  // Hardcoded values, no environment, no provider.
18
  static readonly testLayer = Layer.succeed(AppConfig, {
19
    port: 9999,
20
    apiKey: "test-key",
21
  })
22
}
23

24
// Business logic depends on the tag.
25
const program = Effect.gen(function* () {
26
  const config = yield* AppConfig
27
  return `Listening on ${config.port}`
28
})

Common Pitfalls

1, Reading Config inside business logic. Depend on a config service, not on Config.int("PORT"). The service is trivially swappable; the raw Config requires a ConfigProvider wired through every test.

2, Defaulting required secrets. Config.redacted("API_KEY") without a default is intentional: missing secrets should fail at startup, not silently fall back to "".

3, Calling Redacted.value too early. Extract at the point of use (the outbound HTTP call). Extracting at the config layer puts the raw secret on every layer-trace log.

4, Reaching for Config.orElse(() => Config.succeed(x)). For a constant fallback, Config.withDefault(x) is the dedicated combinator. Use orElse only when the fallback is itself a Config.

`Config.boolean`. - [ ] Wrap a secret with `Config.redacted` and provide a default with `Config.withDefault`. - [ ] Swap the default provider for a test `Map` and re-run the effect. - [ ] Expose the resolved config as a service so business code yields it like any other dependency.

The full test suite

The index.test.ts for this lesson, verbatim from steps/25-config/.

1
import { describe, it, expect } from "vite-plus/test"
2
import { Effect, Config, ConfigProvider, Layer, Context, Redacted } from "effect"
3

4
const providerFromMap = (entries: Map<string, string>) =>
5
  ConfigProvider.fromUnknown(Object.fromEntries(entries))
6

7
// =============================================================================
8
// 23 - Config: Type-Safe Configuration
9
// =============================================================================
10
//
11
// A Config<A> is a description of how to read a value. The ConfigProvider
12
// interprets it. Default provider: process.env. Tests: providerFromMap.
13

14
describe("23 - Config", () => {
15
  // @beat
16
  //   id: primitive-readers
17
  //   shape: one-todo
18
  //   title: Read typed primitives from the environment
19
  //   teaches: Config.int, Config.string, and Config.boolean describe a typed read interpreted by a ConfigProvider.
20
  //   hint: Effect.provideService(ConfigProvider.ConfigProvider, providerFromMap(new Map([["KEY", "value"]])))
21
  describe("primitive readers", () => {
22
    it("Config.int parses a numeric environment variable", async () => {
23
      //      ┌─── Effect<number, ConfigError>
24
      //      ▼
25
      const program = Config.int("PORT")
26

27
      const result = await Effect.runPromise(
28
        program.pipe(
29
          Effect.provideService(ConfigProvider.ConfigProvider,
30
            providerFromMap(new Map([["PORT", "3000"]])),
31
          ),
32
        ),
33
      )
34

35
      expect(result).toBe(3000)
36
    })
37

38
    it("Config.string reads a string", async () => {
39
      const result = await Effect.runPromise(
40
        Config.string("HOST").pipe(
41
          Effect.provideService(ConfigProvider.ConfigProvider,
42
            providerFromMap(new Map([["HOST", "localhost"]])),
43
          ),
44
        ),
45
      )
46

47
      expect(result).toBe("localhost")
48
    })
49

50
    it("Config.boolean parses true/false/1/0", async () => {
51
      const result = await Effect.runPromise(
52
        Config.boolean("DEBUG").pipe(
53
          Effect.provideService(ConfigProvider.ConfigProvider,
54
            providerFromMap(new Map([["DEBUG", "true"]])),
55
          ),
56
        ),
57
      )
58

59
      expect(result).toBe(true)
60
    })
61
  })
62
  // @end-beat
63

64
  // @beat
65
  //   id: redacted-and-default
66
  //   shape: one-todo
67
  //   title: Secrets and fallbacks
68
  //   teaches: Config.redacted wraps secrets so logs cannot leak them; Config.withDefault supplies a constant fallback when absent.
69
  //   hint: Redacted.value(secret) at the point of use; .pipe(Config.withDefault(8080)) for optional settings
70
  describe("Config.redacted", () => {
71
    it("hides the value from logs and toString", async () => {
72
      //      ┌─── Redacted<string>
73
      //      ▼
74
      const program = Effect.gen(function* () {
75
        const secret = yield* Config.redacted("API_KEY")
76
        return Redacted.value(secret)
77
      })
78

79
      const result = await Effect.runPromise(
80
        program.pipe(
81
          Effect.provideService(ConfigProvider.ConfigProvider,
82
            providerFromMap(new Map([["API_KEY", "super-secret-123"]])),
83
          ),
84
        ),
85
      )
86

87
      expect(result).toBe("super-secret-123")
88
    })
89
  })
90

91
  describe("Config.withDefault", () => {
92
    it("falls back when the variable is absent", async () => {
93
      const result = await Effect.runPromise(
94
        Config.int("MISSING_PORT")
95
          .pipe(Config.withDefault(8080))
96
          .pipe(Effect.provideService(ConfigProvider.ConfigProvider, providerFromMap(new Map()))),
97
      )
98

99
      expect(result).toBe(8080)
100
    })
101

102
    it("uses the variable when present", async () => {
103
      const result = await Effect.runPromise(
104
        Config.int("PORT")
105
          .pipe(Config.withDefault(8080))
106
          .pipe(
107
            Effect.provideService(ConfigProvider.ConfigProvider,
108
              providerFromMap(new Map([["PORT", "4000"]])),
109
            ),
110
          ),
111
      )
112

113
      expect(result).toBe(4000)
114
    })
115
  })
116
  // @end-beat
117

118
  // @beat
119
  //   id: config-as-service
120
  //   shape: multi-todo
121
  //   title: Wrap Config in a service Layer
122
  //   teaches: Business logic depends on a Context.Service — production reads via Layer.effect, tests use Layer.succeed with no provider.
123
  //   hint: static readonly layer = Layer.effect(AppConfig, Effect.gen(function* () { ... }))
124
  describe("Config as a service", () => {
125
    class AppConfig extends Context.Service<
126
      AppConfig,
127
      { readonly port: number; readonly apiKey: string }
128
    >()("AppConfig") {
129
      static readonly layer = Layer.effect(
130
        AppConfig,
131
        Effect.gen(function* () {
132
          const port = yield* Config.int("PORT").pipe(
133
            Config.withDefault(3000),
134
          )
135
          const apiKey = yield* Config.redacted("API_KEY")
136
          return { port, apiKey: Redacted.value(apiKey) }
137
        }),
138
      )
139

140
      static readonly testLayer = Layer.succeed(AppConfig, {
141
        port: 9999,
142
        apiKey: "test-key",
143
      })
144
    }
145

146
    it("business logic depends on the service tag, not Config", async () => {
147
      const program = Effect.gen(function* () {
148
        const config = yield* AppConfig
149
        return `Server on ${config.port} with key ${config.apiKey}`
150
      })
151

152
      const result = await Effect.runPromise(
153
        program.pipe(Effect.provide(AppConfig.testLayer)),
154
      )
155

156
      expect(result).toBe("Server on 9999 with key test-key")
157
    })
158

159
    it("production layer reads from the ambient provider", async () => {
160
      const program = Effect.gen(function* () {
161
        const config = yield* AppConfig
162
        return config.port
163
      })
164

165
      const result = await Effect.runPromise(
166
        program.pipe(
167
          Effect.provide(AppConfig.layer),
168
          Effect.provideService(ConfigProvider.ConfigProvider,
169
            providerFromMap(
170
              new Map([
171
                ["PORT", "4000"],
172
                ["API_KEY", "prod-key"],
173
              ]),
174
            ),
175
          ),
176
        ),
177
      )
178

179
      expect(result).toBe(4000)
180
    })
181

182
    it("a missing required secret fails at startup", async () => {
183
      const program = Effect.gen(function* () {
184
        const config = yield* AppConfig
185
        return config.apiKey
186
      })
187

188
      const exit = await Effect.runPromiseExit(
189
        program.pipe(
190
          Effect.provide(AppConfig.layer),
191
          Effect.provideService(ConfigProvider.ConfigProvider,
192
            providerFromMap(new Map([["PORT", "3000"]])),
193
          ),
194
        ),
195
      )
196

197
      expect(exit._tag).toBe("Failure")
198
    })
199
  })
200
  // @end-beat
201

202
  // @beat
203
  //   id: test-provider
204
  //   shape: one-todo
205
  //   title: Isolate tests from process.env
206
  //   teaches: providerFromMap supplies a deterministic source so tests never touch the real environment.
207
  //   hint: Effect.provideService(ConfigProvider.ConfigProvider, providerFromMap(new Map([...])))
208
  describe("providerFromMap isolates tests from process.env", () => {
209
    it("reads multiple values from a deterministic source", async () => {
210
      const program = Effect.gen(function* () {
211
        const port = yield* Config.int("PORT")
212
        const host = yield* Config.string("HOST")
213
        return { port, host }
214
      })
215

216
      const result = await Effect.runPromise(
217
        program.pipe(
218
          Effect.provideService(ConfigProvider.ConfigProvider,
219
            providerFromMap(
220
              new Map([
221
                ["PORT", "8080"],
222
                ["HOST", "test-host"],
223
              ]),
224
            ),
225
          ),
226
        ),
227
      )
228

229
      expect(result).toEqual({ port: 8080, host: "test-host" })
230
    })
231
  })
232
  // @end-beat
233
})

04·01Config

25 - Config: Type-Safe Configuration

What you’ll work through

The Boundary

`Config.string`, `integer`, `number`, `boolean`

`Config.redacted`

`Config.withDefault`

`Config.all`

`Effect.provideService` for Tests

Config as a Service

Common Pitfalls

See Also

The full test suite

04·01Config

25 - Config: Type-Safe Configuration

What you’ll work through

The Boundary

Config.string, integer, number, boolean

Config.redacted

Config.withDefault

Config.all

Effect.provideService for Tests

Config as a Service

Common Pitfalls

See Also

The full test suite

`Config.string`, `integer`, `number`, `boolean`

`Config.redacted`

`Config.withDefault`

`Config.all`

`Effect.provideService` for Tests