API Reference

Public fragment, composition, source, inference, resolver, result, and error APIs.

Environment definition

`server(values, options?)`

Creates an immutable server fragment. options accepts:

{
  runtimeEnv?: RuntimeEnv;
  prefix?: string;
  emptyStringAsUndefined?: boolean;
}

The runtime source defaults to process.env. Values may contain static values, Effect Schemas whose outputs are not functions, fromEnv definitions, and fromResolver definitions.

`client(values, options?)`

Creates an immutable public client fragment with the same runtime options. runtimeEnv is required when values contains a schema. Resolver-backed and redacted definitions are rejected.

`shared(values)`

Creates an immutable fragment of public static values available to both contexts. Schemas and redacted values are rejected.

`createEnv(...fragments)`

Creates one AppEnv from server, client, and shared fragments:

const appEnv = createEnv(
  shared({ APP_NAME: "My App" }),
  server({ DATABASE_URL: postgresUrl }),
  client({ APP_URL: url }, { runtimeEnv: import.meta.env }),
);

The returned object exposes two lazy Effect properties:

appEnv.server
appEnv.client

The server Effect produces server, client, and shared values. The client Effect produces client and shared values.

`extendEnv(...inputs)`

Returns a pipeable extension function:

const appEnv = baseEnv.pipe(
  extendEnv(featureEnv),
  extendEnv(server({ PORT: port })),
);

Inputs may be AppEnv values or individual fragments. They are applied from left to right, and the last complete definition for a key wins. createEnv does not accept existing AppEnv values.

`fromEnv(name)`

Schema pipe combinator that maps one property to an exact runtime name:

API_KEY: requiredString.pipe(fromEnv("PUBLIC_API_KEY"))

Apply schema combinators before fromEnv; the returned sourced definition is terminal so the source cannot be accidentally erased.

Runtime sources accept an environment object, parsed JSON object, or ReadonlyMap<string, unknown>. Object sources support exact keys and dot-separated paths; exact keys take precedence. Map sources use exact keys.

Resolvers

`configureResolver(adapter, options)`

Configures any ResolverAdapter with ordinary runtime options. No compiler metadata is required from custom adapters. The configured resolver can be reused by multiple fromResolver definitions.

Resolver adapters receive requested provider references as referencesByKey, keyed by application property:

resolve: ({ referencesByKey }) =>
  Effect.succeed({
    TOKEN: resolveReference(referencesByKey.TOKEN),
  })

`fromResolver(resolver, reference)`

Makes one server variable authoritative from a provider reference:

TOKEN: requiredString.pipe(
  fromResolver(aws, "production/token"),
)

Resolver-backed schemas are server-only, automatically redacted, and batched by configured resolver.

Built-in adapters

awsSecretsAdapter
gcpSecretsAdapter
azureKeyVaultAdapter
onePasswordSecretsAdapter
customSecretsAdapter

Inference

InferServerEnv<typeof appEnv>
InferClientEnv<typeof appEnv>
InferEnv<typeof appEnv.server>
InferEnv<typeof appEnv.client>

InferEnv also accepts Promise-like materialization results.

Result conversion

`asResult()`

Converts only an Effect’s typed error channel:

const result = await Effect.runPromise(
  appEnv.server.pipe(asResult()),
);

Defects and interruptions are not converted into result values.

Errors

`EnvValidationError`

Contains frozen, secret-safe issues for missing and invalid values.

`EnvConfigurationError`

Reports invalid fragments, duplicate runtime mappings, malformed runtime sources, and malformed resolver results.

`ServerEnvironmentAccessError`

An EnvConfigurationError subclass returned when appEnv.server executes in a client or unproven runtime.

`EnvironmentAccessError`

An EnvConfigurationError subclass raised when code reads a property that is not present in the materialized target.

Resolver errors

ResolverConfigurationError
ResolverInitializationError
ResolverRequestFailed
ResolverResponseDecodeFailed

Build plugins

@ayronforge/envil/plugins/vite
@ayronforge/envil/plugins/rollup
@ayronforge/envil/plugins/rolldown
@ayronforge/envil/plugins/webpack
@ayronforge/envil/plugins/rspack
@ayronforge/envil/plugins/esbuild