Configuration

Effect separates the description of a configuration from the source that supplies its values:

• A Config<T> describes how to load and decode a value of type T. It is also an Effect<T, ConfigError>, so it can be yielded directly inside Effect.gen.
• A ConfigProvider supplies the raw values. The default provider reads environment variables.

Keeping these concerns separate lets application code define its requirements once and choose a different provider for production, local development, or tests.

Defining and Parsing a Config

Use the constructors in the Config module for individual values and Config.all to combine them.

Example (Parsing a Config with a Specific Provider)

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

3
const AppConfig = Config.all({
4
  host: Config.nonEmptyString("HOST"),
5
  port: Config.port("PORT"),
6
})
7

8
const provider = ConfigProvider.fromEnv({
9
  env: {
10
    HOST: "localhost",
11
    PORT: "8080",
12
  },
13
})
14

15
const result = Effect.runSync(AppConfig.parse(provider))
16

17
result // => { host: "localhost", port: 8080 }

Calling config.parse(provider) is useful when the provider is already available explicitly, especially in tests.

In application code, a Config can instead be yielded as an Effect. It then uses the ConfigProvider installed in the Effect context. When no provider is installed explicitly, Effect uses ConfigProvider.fromEnv().

Example (Using the Default Environment Provider)

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

3
const AppConfig = Config.all({
4
  host: Config.nonEmptyString("HOST"),
5
  port: Config.port("PORT").pipe(Config.withDefault(8080)),
6
})
7

8
const program = Effect.gen(function* () {
9
  const { host, port } = yield* AppConfig
10
  console.log(`Application started: ${host}:${port}`)
11
})
12

13
Effect.runPromise(program)

HOST=localhost PORT=3000 npx tsx app.ts

Application started: localhost:3000

Built-in Config Values

Effect provides convenience constructors for common scalar values:

For ordinary numeric settings, prefer Config.finite. Config.number also accepts non-finite values such as NaN and Infinity, which are rarely valid configuration values.

Config.boolean accepts the case-sensitive strings true, false, yes, no, on, off, 1, 0, y, and n.

Using Config with Schema

Use Config.schema when a setting needs a custom type, validation, or a structured representation. The provider supplies the encoded representation and the resulting Config produces the schema’s Type.

Example (Validating a Configuration Value)

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

3
const Username = Schema.String.check(
4
  Schema.isMinLength(4, { message: "Expected at least 4 characters" }),
5
)
6

7
const username = Config.schema(Username, "USERNAME")
8
const provider = ConfigProvider.fromEnv({ env: { USERNAME: "alice" } })
9

10
Effect.runSync(username.parse(provider)) // => "alice"

Schemas can also describe an entire configuration object.

Example (Reading Structured Configuration)

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

3
const ServerConfig = Config.schema(
4
  Schema.Struct({
5
    host: Schema.String,
6
    port: Config.Port,
7
  }),
8
  "server",
9
)
10

11
const provider = ConfigProvider.fromUnknown({
12
  server: {
13
    host: "localhost",
14
    port: 8080,
15
  },
16
})
17

18
Effect.runSync(ServerConfig.parse(provider)) // => { host: "localhost", port: 8080 }

Config.schema derives a tree-shaped string encoding from the schema. This allows the same structured config to read SERVER_HOST and SERVER_PORT from an environment provider, or { server: { host, port } } from ConfigProvider.fromUnknown.

See Schema: Config for more details.

Arrays and Records

Config.Array and Config.Record are schemas for values that may be supplied either structurally or as one separated string. Pass them to Config.schema; they are not Config combinators.

Example (Reading a Comma-Separated Array)

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

3
const exporters = Config.schema(Config.Array(Schema.String), "EXPORTERS")
4
const provider = ConfigProvider.fromEnv({
5
  env: { EXPORTERS: "otlp,prometheus" },
6
})
7

8
Effect.runSync(exporters.parse(provider)) // => ["otlp", "prometheus"]

Config.Record(key, value) similarly accepts either a record or a string such as "service.name=api,service.version=1.0". Both schemas accept options for customizing their separators.

Plain Schema.Array and Schema.Record remain useful when the provider must supply a structural array or object rather than a separated scalar value.

Combining Configs

Config.all combines configs into a tuple or a named object while preserving the input shape.

Example (Combining and Nesting Configs)

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

3
const DatabaseConfig = Config.all({
4
  host: Config.nonEmptyString("HOST"),
5
  port: Config.port("PORT"),
6
}).pipe(Config.nested("DATABASE"))
7

8
const provider = ConfigProvider.fromEnv({
9
  env: {
10
    DATABASE_HOST: "localhost",
11
    DATABASE_PORT: "5432",
12
  },
13
})
14

15
Effect.runSync(DatabaseConfig.parse(provider)) // => { host: "localhost", port: 5432 }

Config.nested(config, path) prepends a string or path to every lookup performed by that config. With ConfigProvider.fromEnv, path segments are joined with _.

For APIs that accept either an already-built Config<T> or a nested record of configs, Config.Wrap<T> and Config.unwrap provide the corresponding input type and conversion.

Defaults and Optional Values

Config.withDefault supplies a value only when none of the relevant input is present.

Example (Providing a Default)

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

3
const port = Config.port("PORT").pipe(Config.withDefault(8080))
4
const provider = ConfigProvider.fromUnknown({})
5

6
Effect.runSync(port.parse(provider)) // => 8080

Invalid input is not treated as missing. For example, PORT=not-a-port still fails instead of silently producing 8080. The same rule applies to a combined config: if part of the group is supplied, a missing or invalid sibling makes the group incomplete rather than replacing the whole group with a default.

Use Config.option when absence should produce an Option instead.

Example (Reading an Optional Value)

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

3
const apiKey = Config.string("API_KEY").pipe(Config.option)
4
const provider = ConfigProvider.fromUnknown({})
5

6
Effect.runSync(apiKey.parse(provider)) // => Option.none()

Falling Back After Any Config Error

Config.orElse is broader than Config.withDefault: it tries another config after any ConfigError, including invalid input.

Example (Falling Back to Another Config)

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

3
const host = Config.string("HOST").pipe(
4
  Config.orElse(() => Config.string("FALLBACK_HOST")),
5
)
6

7
const provider = ConfigProvider.fromUnknown({ FALLBACK_HOST: "localhost" })
8

9
Effect.runSync(host.parse(provider)) // => "localhost"

Because orElse can recover from validation errors, use it only when replacing invalid input is intentional. Use withDefault for the common case where only absence should trigger a fallback.

Transforming Values

Use Config.map for a transformation that cannot fail.

Example (Mapping a Config)

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

3
const origin = Config.all({
4
  host: Config.nonEmptyString("HOST"),
5
  port: Config.port("PORT"),
6
}).pipe(Config.map(({ host, port }) => `http://${host}:${port}`))
7

8
const provider = ConfigProvider.fromUnknown({
9
  HOST: "localhost",
10
  PORT: 8080,
11
})
12

13
Effect.runSync(origin.parse(provider)) // => "http://localhost:8080"

For validation and parsing, prefer expressing the rules in a schema and using Config.schema. Config.mapOrFail is available when a transformation instead needs to return an Effect<B, ConfigError>.

Handling Sensitive Values

Config.redacted wraps a string in Redacted<string>, whose string representation does not reveal the value. Accessing the secret requires an explicit call to Redacted.value.

Example (Protecting a Secret)

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

3
const apiKey = Config.redacted("API_KEY")
4
const provider = ConfigProvider.fromEnv({
5
  env: { API_KEY: "secret-value" },
6
})
7

8
const result = Effect.runSync(apiKey.parse(provider))
9

10
String(result) // => "<redacted>"
11
Redacted.value(result) // => "secret-value"

To decode a value and then wrap it, combine Config.schema with Schema.RedactedFromValue.

1
import { Config, ConfigProvider, Effect, Redacted, Schema } from "effect"
2

3
const secretNumber = Config.schema(
4
  Schema.RedactedFromValue(Schema.FiniteFromString),
5
  "SECRET_NUMBER",
6
)
7

8
const provider = ConfigProvider.fromEnv({
9
  env: { SECRET_NUMBER: "42" },
10
})
11

12
const result = Effect.runSync(secretNumber.parse(provider))
13

14
Redacted.value(result) // => 42

Config Providers

The ConfigProvider module includes providers for several common sources:

fromEnv merges process.env and import.meta.env by default. Passing { env } replaces that source, which makes it convenient for tests and non-Node runtimes.

Both fromEnv and fromUnknown treat an empty string as missing by default. Pass { preserveEmptyStrings: true } when an empty string is a meaningful value.

Loading an In-Memory Object

Use ConfigProvider.fromUnknown for a JavaScript value or parsed JSON object. Object keys and array indexes become configuration path segments.

Example (Loading a Parsed JSON Object)

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

3
const provider = ConfigProvider.fromUnknown(
4
  JSON.parse(`{"server":{"host":"localhost","port":8080}}`),
5
)
6

7
const server = Config.all({
8
  host: Config.string("host"),
9
  port: Config.port("port"),
10
}).pipe(Config.nested("server"))
11

12
Effect.runSync(server.parse(provider)) // => { host: "localhost", port: 8080 }

Loading .env Files and Directories

ConfigProvider.fromDotEnvContents parses an already-loaded string. ConfigProvider.fromDotEnv() reads .env from the current directory by default and returns an Effect that requires the FileSystem service.

ConfigProvider.fromDir() reads each file as a leaf value and each directory as a record. This is useful for configuration mounted as files, such as Kubernetes ConfigMaps and Secrets. It requires the FileSystem and Path services.

Transforming Provider Paths

Provider combinators change how all configs look up their paths:

• ConfigProvider.nested prefixes every lookup.
• ConfigProvider.constantCase converts string path segments to CONSTANT_CASE.
• ConfigProvider.mapInput performs an arbitrary path transformation.

Example (Adapting camelCase Keys to Environment Variables)

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

3
const provider = ConfigProvider.fromEnv({
4
  env: { DATABASE_HOST: "localhost" },
5
}).pipe(ConfigProvider.constantCase)
6

7
const databaseHost = Config.string("databaseHost")
8

9
Effect.runSync(databaseHost.parse(provider)) // => "localhost"

Combining Providers

ConfigProvider.orElse(primary, fallback) consults the fallback only when the primary provider has no value at a requested path. Unlike Config.orElse, it does not recover from source errors or schema validation errors.

Example (Adding Provider Defaults)

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

3
const environment = ConfigProvider.fromEnv({
4
  env: { HOST: "production.example.com" },
5
})
6

7
const defaults = ConfigProvider.fromUnknown({
8
  HOST: "localhost",
9
  PORT: 8080,
10
})
11

12
const provider = ConfigProvider.orElse(environment, defaults)
13
const app = Config.all({
14
  host: Config.string("HOST"),
15
  port: Config.port("PORT"),
16
})
17

18
Effect.runSync(app.parse(provider)) // => { host: "production.example.com", port: 8080 }

Installing a Provider

Use ConfigProvider.layer(provider) to replace the provider used by configs yielded as Effects. ConfigProvider.layerAdd(provider) instead adds a fallback to the current provider; pass { asPrimary: true } to make the added provider take precedence.

Example (Providing a ConfigProvider Layer)

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

3
const provider = ConfigProvider.fromUnknown({ PORT: 8080 })
4
const ProviderLayer = ConfigProvider.layer(provider)
5

6
const program = Effect.gen(function* () {
7
  return yield* Config.port("PORT")
8
})
9

10
Effect.runSync(Effect.provide(program, ProviderLayer)) // => 8080

For a single config, config.parse(provider) is simpler and does not change the provider for the rest of the Effect program.