Effect Config Schema

Config & Schema

When to use

• Validating request bodies, params, or external inputs
• Loading environment configuration with types

Config (example)

import { Config } from "effect"

const Server = Config.nested("SERVER")(Config.all({
  host: Config.string("HOST"),
  port: Config.number("PORT")
}))

Schema Validate

import { Schema as S } from "effect"

const User = S.Struct({ id: S.Number, name: S.String })
const decodeUser = (u: unknown) => S.decodeUnknown(User)(u)

Transform

const IsoDate = S.String // then transform to Date in pipeline where needed

Real-world snippet: Layer selecting AWS credentials via Config options

class AwsCredentials extends Effect.Service<AwsCredentials>()("AwsCredentials", {
  effect: Effect.gen(function* () {
    const accessKeys = yield* Config.option(
      Config.all([Config.string("CAP_AWS_ACCESS_KEY"), Config.string("CAP_AWS_SECRET_KEY")])
    )
    const vercelAwsRole = yield* Config.option(Config.string("VERCEL_AWS_ROLE_ARN"))

    const credentials = yield* Effect.gen(function* () {
      if (Option.isSome(vercelAwsRole)) return awsCredentialsProvider({ roleArn: vercelAwsRole.value })
      if (Option.isSome(accessKeys)) {
        const [accessKeyId, secretAccessKey] = accessKeys.value
        return { accessKeyId, secretAccessKey }
      }
      return fromContainerMetadata()
    })

    return { credentials }
  })
})

Guidance

• Prefer schemas close to boundaries; keep core logic typed
• For branded types (Email, PositiveInt), use transform/brand helpers
• Validate early, map to domain errors in one place

Pitfalls

• Accepting unknown into core → always decode first
• Large ad-hoc validation code → centralize in Schema

Cross-links

• HTTP & Routing for endpoint validation
• Foundations for operator style

Local Source Reference

CRITICAL: Search local Effect source before implementing

The full Effect source code is available at docs/effect-source/. Always search the actual implementation before writing Effect code.

Key Source Files

• Config: docs/effect-source/effect/src/Config.ts
• Schema: docs/effect-source/schema/src/Schema.ts

Example Searches

# Find Config patterns and options
grep -F "Config.string" docs/effect-source/effect/src/Config.ts
grep -F "Config.number" docs/effect-source/effect/src/Config.ts
grep -F "Config.option" docs/effect-source/effect/src/Config.ts

# Study Schema validation
grep -F "Struct" docs/effect-source/schema/src/Schema.ts
grep -F "decodeUnknown" docs/effect-source/schema/src/Schema.ts

# Find Schema transforms
grep -rF "transform" docs/effect-source/schema/src/
grep -rF "brand" docs/effect-source/schema/src/

# Look at Config test examples
grep -F "Config." docs/effect-source/effect/test/Config.test.ts

Workflow

1. Identify the Config or Schema API you need
2. Search docs/effect-source/effect/src/Config.ts or docs/effect-source/schema/src/Schema.ts
3. Study the types and validation patterns
4. Look at test files for usage examples
5. Write your code based on real implementations

Real source code > documentation > assumptions

References

• Agent Skills overview: https://www.anthropic.com/news/skills
• Skills guide: https://docs.claude.com/en/docs/claude-code/skills