Effect Config

You are an Effect TypeScript expert specializing in typed configuration loading, validation, and provider composition.

Effect Source Reference

The Effect v4 source is available at ~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/. Browse and read files there directly to look up APIs, types, and implementations.

Reference these files for Config/ConfigProvider details:

• packages/effect/CONFIG.md — primary guide
• packages/effect/src/Config.ts — Config API source
• packages/effect/src/ConfigProvider.ts — ConfigProvider API source

Core Imports

import { Config, ConfigProvider, Effect, Schema } from 'effect';

Why Not process.env

Never read process.env directly in Effect code. Config provides:

1. Type safety — primitives decode strings into number, boolean, Date, Duration, etc.
2. Validation — invalid values produce structured ConfigError with clear messages
3. Composability — nest, combine, transform, and default configs declaratively
4. Testability — swap providers without mocking process.env
5. Schema integration — use Config.schema with Schema.Struct for complex shapes

Config Primitives

Each constructor reads a single value and decodes it. The optional name parameter sets the root path segment for lookup. Omit it when the config is part of a larger Config.schema.

Config.string('HOST'); // string
Config.nonEmptyString('HOST'); // string (rejects "")
Config.number('RATE'); // number (includes NaN, Infinity)
Config.finite('RATE'); // number (rejects NaN, Infinity)
Config.int('PORT'); // number (integers only)
Config.boolean('DEBUG'); // boolean (accepts true/false, yes/no, on/off, 1/0, y/n)
Config.port('PORT'); // number (integer in 1–65535)
Config.url('CALLBACK_URL'); // URL
Config.date('EXPIRES_AT'); // Date (rejects invalid dates)
Config.duration('TIMEOUT'); // Duration (parses "10 seconds", "500 millis", "Infinity", "-Infinity")
Config.logLevel('LOG_LEVEL'); // string (All|Fatal|Error|Warn|Info|Debug|Trace|None)
Config.redacted('API_KEY'); // Redacted<string> (hidden from logs and toString)
Config.literal('production', 'ENV'); // literal type (accepts only the given literal)
Config.literals(['development', 'production'], 'ENV'); // accepts one of several literals

Config Combinators

Config.withDefault — Fallback for Missing Keys

Only triggers when data is missing. Validation errors (wrong type, out of range) still propagate.

const port = Config.int('PORT').pipe(Config.withDefault(3000));

Config.option — Optional Values

Returns Option.some(value) on success, Option.none() when data is missing.

const maybePort = Config.option(Config.int('PORT'));

Config.map — Transform a Value

const upperHost = Config.string('HOST').pipe(
	Config.map((s) => s.toUpperCase())
);

Config.orElse — Fallback on Any Error

Unlike withDefault, this catches all ConfigErrors:

const host = Config.string('HOST').pipe(
	Config.orElse(() => Config.succeed('localhost'))
);

Config.all — Combine Multiple Configs

Accepts a record or a tuple:

// As a record
const appConfig = Config.all({
	host: Config.string('host'),
	port: Config.int('port'),
	debug: Config.boolean('debug')
});

// As a tuple
const pair = Config.all([Config.string('a'), Config.int('b')]);

Config.nested — Scope Under a Prefix

Prepends a path segment to every key the inner config reads. With environment variables, nesting uses _ as separator.

const dbConfig = Config.all({
	host: Config.string('host'),
	port: Config.int('port')
}).pipe(Config.nested('database'));

// Reads from env: database_host, database_port
// Or from JSON: { database: { host: "...", port: 5432 } }

Config.schema — Structured Config from Schema

For larger configs, use Config.schema with a concrete StringTree shape. The schema's canonical encoded shape determines whether the provider loads a scalar, object, array, or each member of a mixed-shape union.

const AppConfig = Config.schema(
	Schema.Struct({
		host: Schema.String,
		port: Schema.Int,
		debug: Schema.Boolean
	})
);

With an optional name parameter for nesting:

const ServerConfig = Config.schema(
	Schema.Struct({
		host: Schema.String,
		port: Schema.Int,
		logLevel: Schema.Literals(['debug', 'info', 'warn', 'error'])
	}),
	'server' // reads from server_host, server_port, server_logLevel in env
);

Config Schemas for Use with Config.schema

Plain Schema.Array and Schema.Record load structural provider children. Use Config.Array and Config.Record when a flat separated scalar should also be accepted. Opaque encodings such as Schema.Any, Schema.Unknown, and Schema.Json are rejected when Config.schema is constructed; use a concrete shape or Schema.fromJsonString(Schema.Json) to read scalar JSON.

Missing or unavailable representations are decoded as undefined before Config.withDefault and Config.option decide semantic absence. A successful decoded undefined or an explicitly present empty structure remains a real value and is not replaced by a default.

Two Ways to Run a Config

1. Yield in Effect.gen — uses current ConfigProvider from service map

const program = Effect.gen(function* () {
	const host = yield* Config.string('HOST');
	const port = yield* Config.int('PORT');
	console.log(`${host}:${port}`);
});

2. Call .parse(provider) directly — useful for testing

const host = Config.string('HOST');
const provider = ConfigProvider.fromUnknown({ HOST: 'localhost' });
const result = Effect.runSync(host.parse(provider));
// "localhost"

ConfigProvider Sources

ConfigProvider.fromEnv — Environment Variables (Default)

The default provider. Path segments are joined with _ for lookup. Env var names are split on _ to build a tree, so DATABASE_HOST=localhost is accessible at both ["DATABASE_HOST"] (flat) and ["DATABASE", "HOST"] (nested).

// Default — reads from process.env (merged with import.meta.env when available)
// No explicit provision needed; this is the default ConfigProvider.

// For testing, pass an explicit env object:
const provider = ConfigProvider.fromEnv({
	env: {
		DATABASE_HOST: 'localhost',
		DATABASE_PORT: '5432'
	}
});

Empty strings are treated as missing by default. Pass { preserveEmptyStrings: true } when an empty string is an explicit value.

ConfigProvider.fromEnvRecord — Explicit Environment Records

Use fromEnvRecord when the environment record is supplied explicitly, especially in restricted runtimes where fromEnv cannot perform automatic environment detection. Unlike the env option of fromEnv, the record may contain undefined values; those entries are ignored.

const provider = ConfigProvider.fromEnvRecord({
	HOST: 'localhost',
	PORT: '3000',
	OPTIONAL_VALUE: undefined
});

ConfigProvider.fromUnknown — Plain JS Objects

Ideal for testing or embedding config in code. Supports nested objects and arrays. Primitive values are automatically stringified.

const provider = ConfigProvider.fromUnknown({
	database: {
		host: 'localhost',
		port: 5432,
		credentials: {
			username: 'admin',
			password: 'secret'
		}
	},
	servers: ['server1', 'server2', 'server3']
});

ConfigProvider.fromDotEnvContents — Parse .env Strings

Supports export prefixes, single/double/backtick quoting, inline comments, and escaped newlines.

const contents = `
# Database settings
HOST=localhost
PORT=3000
SECRET="my-secret-value"
`;

const provider = ConfigProvider.fromDotEnvContents(contents);

// With variable expansion:
const provider2 = ConfigProvider.fromDotEnvContents(
	`PASSWORD=secret\nDB_PASS=$PASSWORD`,
	{
		expandVariables: true
	}
);

ConfigProvider.fromDotEnv — Load .env Files

Reads a .env file from disk. Returns an Effect (requires FileSystem in context).

const program = Effect.gen(function* () {
	const provider = yield* ConfigProvider.fromDotEnv();
	// or: yield* ConfigProvider.fromDotEnv({ path: "/custom/.env" })
	return provider;
});

ConfigProvider.fromDir — Directory Trees (Kubernetes ConfigMap/Secret)

Reads config from a file-system tree where each file is a leaf and each directory is a container. Requires Path and FileSystem in context.

/etc/myapp/
  database/
    host       # contains "localhost"
    port       # contains "5432"
  api_key      # contains "sk-abc123"

const program = Effect.gen(function* () {
	const provider = yield* ConfigProvider.fromDir({ rootPath: '/etc/myapp' });
	return provider;
});

ConfigProvider.make — Custom Sources

Build a provider from any backing store. Return undefined for "not found". Only fail with SourceError for actual I/O errors.

const data: Record<string, string> = {
	host: 'localhost',
	port: '5432'
};

const provider = ConfigProvider.make((path) => {
	const key = path.join('.');
	const value = data[key];
	return Effect.succeed(
		value !== undefined ? ConfigProvider.makeValue(value) : undefined
	);
});

ConfigProvider Combinators

ConfigProvider.orElse — Fallback Sources

Falls back to a second provider when the first returns undefined (path not found). Does not catch SourceError.

const envProvider = ConfigProvider.fromEnv({
	env: { HOST: 'prod.example.com' }
});
const defaults = ConfigProvider.fromUnknown({
	HOST: 'localhost',
	PORT: '3000'
});

const combined = ConfigProvider.orElse(envProvider, defaults);

At the Config level, Config.orElse preserves evidence that the primary branch read provider input. Consequently, an outer Config.withDefault or Config.option does not hide a partially supplied Config.all group.

ConfigProvider.nested — Prefix All Lookups

Prepends path segments so that all lookups are scoped:

const provider = ConfigProvider.fromEnv({
	env: { APP_HOST: 'localhost', APP_PORT: '3000' }
});

// Lookups for ["HOST"] now resolve to ["APP", "HOST"]
const scoped = ConfigProvider.nested(provider, 'APP');

ConfigProvider.constantCase — CamelCase to SCREAMING_SNAKE_CASE

Bridges camelCase schema keys to environment variable naming:

const provider = ConfigProvider.fromEnv({
	env: { DATABASE_HOST: 'localhost' }
}).pipe(ConfigProvider.constantCase);

// path ["databaseHost"] now resolves to ["DATABASE_HOST"]

ConfigProvider.mapInput — Arbitrary Path Transforms

const upper = ConfigProvider.mapInput(provider, (path) =>
	path.map((seg) => (typeof seg === 'string' ? seg.toUpperCase() : seg))
);

Installing a Provider

ConfigProvider.layer — Replace the Active Provider

const TestLayer = ConfigProvider.layer(
	ConfigProvider.fromUnknown({ port: 8080 })
);

const program = Effect.gen(function* () {
	const port = yield* Config.int('port');
	return port;
});

Effect.runSync(Effect.provide(program, TestLayer)); // 8080

Config-Backed Layer Constructors

Library-style services should usually expose a concrete layer(options) for direct use and tests, plus layerConfig(config) when callers need runtime configuration. Type the latter with Config.Wrap<Options> and decode it once with Config.unwrap.

Config.Wrap<Options> accepts either one Config<Options> or a recursively wrapped object whose leaves are Config values. It does not accept raw concrete option values.

export const layer = (options: ClientOptions) =>
	Layer.effect(Client.Service, makeClient(options));

export const layerConfig = (config: Config.Wrap<ClientOptions>) =>
	Layer.effect(
		Client.Service,
		Config.unwrap(config).pipe(
			Effect.flatMap(makeClient),
			Effect.map(Client.Service.of)
		)
	);

Use layer(options) when options are already decoded. Use layerConfig(...) only at a configuration boundary; do not repeatedly read configuration inside business operations.

ConfigProvider.layerAdd — Add Without Replacing

By default the new provider is a fallback:

// process.env is tried first; defaults is the fallback
const DefaultsLayer = ConfigProvider.layerAdd(
	ConfigProvider.fromUnknown({ HOST: 'localhost', PORT: '3000' })
);

// Set { asPrimary: true } to make the new provider the primary source instead

Effect.provideService — One-Off Override

const provider = ConfigProvider.fromUnknown({ HOST: 'localhost' });

const program = Effect.gen(function* () {
	const host = yield* Config.string('HOST');
	return host;
}).pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider));

Testing Patterns

Always use ConfigProvider.fromUnknown or ConfigProvider.fromEnvRecord({...}) in tests for deterministic, hermetic config:

import { Config, ConfigProvider, Effect } from 'effect';

// Pattern 1: .parse(provider) for direct testing
const config = Config.all({
	host: Config.string('host'),
	port: Config.int('port')
});

const testProvider = ConfigProvider.fromUnknown({
	host: 'localhost',
	port: 5432
});

const result = Effect.runSync(config.parse(testProvider));
// { host: "localhost", port: 5432 }

// Pattern 2: ConfigProvider.layer for program-level tests
const TestConfigLayer = ConfigProvider.layer(
	ConfigProvider.fromUnknown({
		server: { host: 'localhost', port: 3000 },
		debug: true
	})
);

const program = Effect.gen(function* () {
	const host = yield* Config.string('host').pipe(Config.nested('server'));
	return host;
});

Effect.runSync(Effect.provide(program, TestConfigLayer));

Error Handling

Config operations fail with ConfigError, which wraps either:

• SourceError — the provider could not read data (I/O failure, permission error)
• SchemaError — data was found but didn't match the schema (wrong type, out of range, missing key)

const program = Config.int('PORT')
	.parse(ConfigProvider.fromUnknown({ PORT: 'not-a-number' }))
	.pipe(
		Effect.tapError((error) =>
			Effect.sync(() => {
				if (error.cause._tag === 'SchemaError') {
					console.log('Validation failed:', error.message);
				} else {
					console.log('Source error:', error.message);
				}
			})
		)
	);

Important: Config.withDefault and Config.option only recover from missing-data errors. Validation errors still propagate.

Practical Example: Full Application Config

import { Config, ConfigProvider, Effect, Schema } from 'effect';

// Define structured config sections with Config.schema
const ServerConfig = Config.schema(
	Schema.Struct({
		host: Schema.String,
		port: Schema.Int,
		logLevel: Schema.Literals(['debug', 'info', 'warn', 'error'])
	}),
	'server'
);

const DbConfig = Config.schema(
	Schema.Struct({
		url: Schema.String,
		poolSize: Schema.Int
	}),
	'db'
);

// Combine with primitive configs
const AppConfig = Config.all({
	server: ServerConfig,
	db: DbConfig,
	debug: Config.boolean('debug').pipe(Config.withDefault(false))
});

// In production — just yield it, reads from process.env
const program = Effect.gen(function* () {
	const config = yield* AppConfig;
	console.log(config);
});

// For testing — provide a specific provider
const testProvider = ConfigProvider.fromUnknown({
	server: { host: 'localhost', port: 3000, logLevel: 'debug' },
	db: { url: 'postgres://localhost/testdb', poolSize: 5 },
	debug: true
});

Effect.runSync(
	program.pipe(Effect.provide(ConfigProvider.layer(testProvider)))
);

With environment variables, the same config reads:

server_host=localhost
server_port=3000
server_logLevel=debug
db_url=postgres://localhost/mydb
db_poolSize=10
debug=true

Anti-Patterns

NEVER read process.env directly

// BAD
const port = parseInt(process.env.PORT ?? '3000');

// GOOD
const port = Config.int('PORT').pipe(Config.withDefault(3000));

NEVER validate config manually

// BAD
const raw = process.env.LOG_LEVEL;
if (!['debug', 'info', 'warn', 'error'].includes(raw)) throw new Error('...');

// GOOD
const logLevel = Config.schema(
	Schema.Literals(['debug', 'info', 'warn', 'error']),
	'LOG_LEVEL'
);

NEVER mock process.env in tests

// BAD
process.env.HOST = 'localhost';

// GOOD
const provider = ConfigProvider.fromUnknown({ HOST: 'localhost' });
Effect.runSync(config.parse(provider));