Envapter

Reads typed environment variables on Node, Bun, and Deno. It adds the filesystem-only configuration APIs: .env path selection, base directory, dotenv options, and per-environment profiles. On the portable build (Workers, the browser, edge) these same APIs warn once and do nothing, unless Envapter.fileApiMode is 'throw'.

AccessorsCopy Anchor Link

baseDirCopy Anchor Link

Get SignatureCopy Anchor Link

get static baseDir(): string | undefined;

The configured base directory, or undefined when relative paths resolve against the working directory.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#reading-from-a-fixed-directory

ReturnsCopy Anchor Link

string | undefined

Set SignatureCopy Anchor Link

set static baseDir(value): void;

Set the base directory that relative .env paths resolve against. Without one they resolve against process.cwd(). It covers the auto-cascade, Envapter.configureProfiles paths, and relative envPaths. Absolute paths always bypass it. Pass a directory path (import.meta.dirname) or a module URL (import.meta.url) to resolve paths next to the calling file regardless of launch directory.

Set this before envPaths so relative envPaths validate against the right directory. Setting undefined restores process.cwd() resolution.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#reading-from-a-fixed-directory

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

debugCopy Anchor Link

Get SignatureCopy Anchor Link

get static debug(): DebugLevel;

ReturnsCopy Anchor Link

DebugLevel

Set SignatureCopy Anchor Link

set static debug(level): void;

Set the debug log level. Defaults to silent. When unset, reads ENVAPT_DEBUG from the bound source on first access. The setter overrides any env-var value. Output goes to stderr on Node (the console elsewhere), prefixed with [envapt].

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/errors#debug-logging

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

Inherited fromCopy Anchor Link

Envapter.debug

envFileOptionsCopy Anchor Link

Get SignatureCopy Anchor Link

get static envFileOptions(): EnvFileOptions;

The env file loader options.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#file-options

ReturnsCopy Anchor Link

EnvFileOptions

Set SignatureCopy Anchor Link

set static envFileOptions(config): void;

Set the env file loader options (encoding, override). Refreshes the cache. Any other key throws InvalidUserDefinedConfig.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#file-options

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

environmentCopy Anchor Link

Get SignatureCopy Anchor Link

get static environment(): Environment;

The current application environment, detected on first read unless you set it.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/environment#detecting-the-environment

ReturnsCopy Anchor Link

Environment

Set SignatureCopy Anchor Link

set static environment(env): void;

Set the application environment to an Environment value such as 'production', matched case-insensitively. An unknown name selects 'development'. Setting it reloads the .env files for that environment.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/environment#detecting-the-environment

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

Inherited fromCopy Anchor Link

Envapter.environment

envPathsCopy Anchor Link

Get SignatureCopy Anchor Link

get static envPaths(): string[];

The configured .env file paths.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#choosing-the-files-yourself

ReturnsCopy Anchor Link

string[]

Set SignatureCopy Anchor Link

set static envPaths(paths): void;

Set custom .env file paths. Setting new paths clears the cache and reloads environment variables. Throws EnvFilesNotFound when a path does not exist.

Once set, these paths replace the dotenv-flow auto-cascade and any Envapter.configureProfiles paths.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#choosing-the-files-yourself

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

fileApiModeCopy Anchor Link

Get SignatureCopy Anchor Link

get static fileApiMode(): FileApiMode;

ReturnsCopy Anchor Link

FileApiMode

Set SignatureCopy Anchor Link

set static fileApiMode(mode): void;

On the portable build, this controls the filesystem-only config APIs (envPaths, baseDir, envFileOptions, configureProfiles, resetPaths). 'warn' (the default) warns once and does nothing. 'throw' throws EnvaptError FileApiUnsupported. The node build runs these APIs normally and this value has no effect there.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/compatibility#file-apis-and-fileapimode

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

Inherited fromCopy Anchor Link

Envapter.fileApiMode

isDevelopmentCopy Anchor Link

Get SignatureCopy Anchor Link

get static isDevelopment(): boolean;

Whether the current environment is development.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/environment#branching-on-the-environment

ReturnsCopy Anchor Link

boolean

Inherited fromCopy Anchor Link

Envapter.isDevelopment

isProductionCopy Anchor Link

Get SignatureCopy Anchor Link

get static isProduction(): boolean;

Whether the current environment is production.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/environment#branching-on-the-environment

ReturnsCopy Anchor Link

boolean

Inherited fromCopy Anchor Link

Envapter.isProduction

isStagingCopy Anchor Link

Get SignatureCopy Anchor Link

get static isStaging(): boolean;

Whether the current environment is staging.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/environment#branching-on-the-environment

ReturnsCopy Anchor Link

boolean

Inherited fromCopy Anchor Link

Envapter.isStaging

isTestCopy Anchor Link

Get SignatureCopy Anchor Link

get static isTest(): boolean;

Whether the current environment is test.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/environment#branching-on-the-environment

ReturnsCopy Anchor Link

boolean

Inherited fromCopy Anchor Link

Envapter.isTest

strictCopy Anchor Link

Get SignatureCopy Anchor Link

get static strict(): boolean;

ReturnsCopy Anchor Link

boolean

Set SignatureCopy Anchor Link

set static strict(value): void;

When true, a whitespace-only value counts as missing, a ${VAR} that can't resolve throws MissingEnvValue, and an empty array element throws EmptyArrayElement. Default false. Setting it clears and rebuilds the cache.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/required-values#strict-mode

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

Inherited fromCopy Anchor Link

Envapter.strict

syncProcessEnvCopy Anchor Link

Get SignatureCopy Anchor Link

get static syncProcessEnv(): boolean;

ReturnsCopy Anchor Link

boolean

Set SignatureCopy Anchor Link

set static syncProcessEnv(value): void;

When true, copies dotenv-loaded keys into process.env. Default false.

envFileOptions.override controls collisions because only keys the loader wrote are copied. With the default false, existing process.env values stay. With true, the file value replaces them in both the cache and process.env.

Flipping false → true copies the loaded keys immediately without a cache refresh. Flipping true → false leaves copied keys in process.env until the process exits.

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#file-options

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

Inherited fromCopy Anchor Link

Envapter.syncProcessEnv

MethodsCopy Anchor Link

configureProfiles()Copy Anchor Link

static configureProfiles(config): void;

Configure per-environment .env path overrides on top of the dotenv-flow auto-cascade.

When set, each Environment key's paths load ahead of the cascade for that environment and win over it, unless envFileOptions.override is true. Unspecified environments still use the cascade as-is. Set useDefaults: false to disable the cascade entirely (load only the configured paths).

Setting an explicit Envapter.envPaths value at any point overrides this configuration.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

ExampleCopy Anchor Link

Envapter.configureProfiles({
  staging: { paths: 'config/staging.env' },
  production: { paths: ['config/prod.env', 'secrets/prod.env'] }
});

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#profiles

get()Copy Anchor Link

static get<Default>(key, fallback?): ConditionalReturn<string, Default>;

Get a string environment variable, or fallback when it is missing or empty. Expands ${VAR} templates in the value. Accepts a single key or an ordered array of keys, read until one has a value. Read any other type with getAs and a converter.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

ConditionalReturn<string, Default>

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/envapter#strings-and-typed-values

Inherited fromCopy Anchor Link

Envapter.get

getAs()Copy Anchor Link

Call SignatureCopy Anchor Link

static getAs<TConverter, TFallback>(
   key, 
   converter, 
   fallback?
): AdvancedConverterReturn<TConverter, TFallback>;

Get an environment variable through a converter: a built-in token such as Converters.Number, an ArrayOf token from Converters.array(...), a custom (raw: string) => T function, or a synchronous Standard Schema (zod, valibot, arktype). A missing value returns the fallback, or undefined without one. A scalar token or a function that can't convert the value returns the fallback too. A bad array element throws ArrayElementConversionFailed. A schema that rejects the value throws SchemaValidationFailed. envapt never runs the schema on the fallback. The key can be a single name or an ordered list, read until one key has a value. A bad converter or fallback throws even when the value is missing.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

AdvancedConverterReturn<TConverter, TFallback>

SeeCopy Anchor Link

• https://envapt.materwelon.dev/docs/envapter#other-types-with-getas
• https://envapt.materwelon.dev/docs/converters#custom-converters

Inherited fromCopy Anchor Link

Envapter.getAs

Call SignatureCopy Anchor Link

static getAs<TReturn>(
   key, 
   converter, 
   fallback
): TReturn;

Get an environment variable through a converter: a built-in token such as Converters.Number, an ArrayOf token from Converters.array(...), a custom (raw: string) => T function, or a synchronous Standard Schema (zod, valibot, arktype). A missing value returns the fallback, or undefined without one. A scalar token or a function that can't convert the value returns the fallback too. A bad array element throws ArrayElementConversionFailed. A schema that rejects the value throws SchemaValidationFailed. envapt never runs the schema on the fallback. The key can be a single name or an ordered list, read until one key has a value. A bad converter or fallback throws even when the value is missing.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

TReturn

SeeCopy Anchor Link

• https://envapt.materwelon.dev/docs/envapter#other-types-with-getas
• https://envapt.materwelon.dev/docs/converters#custom-converters

Inherited fromCopy Anchor Link

Envapter.getAs

Call SignatureCopy Anchor Link

static getAs<TReturn>(
   key, 
   converter, 
   fallback?
): TReturn | undefined;

Get an environment variable through a converter: a built-in token such as Converters.Number, an ArrayOf token from Converters.array(...), a custom (raw: string) => T function, or a synchronous Standard Schema (zod, valibot, arktype). A missing value returns the fallback, or undefined without one. A scalar token or a function that can't convert the value returns the fallback too. A bad array element throws ArrayElementConversionFailed. A schema that rejects the value throws SchemaValidationFailed. envapt never runs the schema on the fallback. The key can be a single name or an ordered list, read until one key has a value. A bad converter or fallback throws even when the value is missing.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

TReturn | undefined

SeeCopy Anchor Link

• https://envapt.materwelon.dev/docs/envapter#other-types-with-getas
• https://envapt.materwelon.dev/docs/converters#custom-converters

Inherited fromCopy Anchor Link

Envapter.getAs

Call SignatureCopy Anchor Link

static getAs<Schema, TFallback>(
   key, 
   schema, 
   fallback?
): ConditionalReturn<InferSchemaOutput<Schema>, TFallback>;

Get an environment variable through a converter: a built-in token such as Converters.Number, an ArrayOf token from Converters.array(...), a custom (raw: string) => T function, or a synchronous Standard Schema (zod, valibot, arktype). A missing value returns the fallback, or undefined without one. A scalar token or a function that can't convert the value returns the fallback too. A bad array element throws ArrayElementConversionFailed. A schema that rejects the value throws SchemaValidationFailed. envapt never runs the schema on the fallback. The key can be a single name or an ordered list, read until one key has a value. A bad converter or fallback throws even when the value is missing.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

ConditionalReturn<InferSchemaOutput<Schema>, TFallback>

SeeCopy Anchor Link

• https://envapt.materwelon.dev/docs/envapter#other-types-with-getas
• https://envapt.materwelon.dev/docs/converters#custom-converters

Inherited fromCopy Anchor Link

Envapter.getAs

Call SignatureCopy Anchor Link

static getAs<TReturn, TFallback>(
   key, 
   converter, 
   fallback?
): ConditionalReturn<NonNullable<TReturn>, TFallback>;

Get an environment variable through a converter: a built-in token such as Converters.Number, an ArrayOf token from Converters.array(...), a custom (raw: string) => T function, or a synchronous Standard Schema (zod, valibot, arktype). A missing value returns the fallback, or undefined without one. A scalar token or a function that can't convert the value returns the fallback too. A bad array element throws ArrayElementConversionFailed. A schema that rejects the value throws SchemaValidationFailed. envapt never runs the schema on the fallback. The key can be a single name or an ordered list, read until one key has a value. A bad converter or fallback throws even when the value is missing.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

ConditionalReturn<NonNullable<TReturn>, TFallback>

SeeCopy Anchor Link

• https://envapt.materwelon.dev/docs/envapter#other-types-with-getas
• https://envapt.materwelon.dev/docs/converters#custom-converters

Inherited fromCopy Anchor Link

Envapter.getAs

getRaw()Copy Anchor Link

static getRaw(key): string | undefined;

Read an environment variable as its raw string, skipping parsing and conversion. A ${NAME} reference in the value comes back unexpanded.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string | undefined

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/envapter#the-raw-string

Inherited fromCopy Anchor Link

Envapter.getRaw

getRequired()Copy Anchor Link

Call SignatureCopy Anchor Link

static getRequired<TConverter>(key, converter): InferConverterReturnType<TConverter>;

Read a required environment variable and convert it, throwing MissingEnvValue when the value is missing or empty. A value it cannot convert throws InvalidEnvValue with issues keyed by the env name. A bad array element, an error a custom parser or schema throws, and a schema's own issues all become issues on that error. Accepts a built-in or ArrayOf token, a custom parser function, or a synchronous Standard Schema. The key can be a single name or an ordered list. A bad converter throws before MissingEnvValue.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

InferConverterReturnType<TConverter>

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/required-values#getrequired-require-and-has

Inherited fromCopy Anchor Link

Envapter.getRequired

Call SignatureCopy Anchor Link

static getRequired<Schema>(key, schema): InferSchemaOutput<Schema>;

Read a required environment variable and convert it, throwing MissingEnvValue when the value is missing or empty. A value it cannot convert throws InvalidEnvValue with issues keyed by the env name. A bad array element, an error a custom parser or schema throws, and a schema's own issues all become issues on that error. Accepts a built-in or ArrayOf token, a custom parser function, or a synchronous Standard Schema. The key can be a single name or an ordered list. A bad converter throws before MissingEnvValue.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

InferSchemaOutput<Schema>

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/required-values#getrequired-require-and-has

Inherited fromCopy Anchor Link

Envapter.getRequired

Call SignatureCopy Anchor Link

static getRequired<TReturnType>(key, converter): NonNullable<TReturnType>;

Read a required environment variable and convert it, throwing MissingEnvValue when the value is missing or empty. A value it cannot convert throws InvalidEnvValue with issues keyed by the env name. A bad array element, an error a custom parser or schema throws, and a schema's own issues all become issues on that error. Accepts a built-in or ArrayOf token, a custom parser function, or a synchronous Standard Schema. The key can be a single name or an ordered list. A bad converter throws before MissingEnvValue.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

NonNullable<TReturnType>

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/required-values#getrequired-require-and-has

Inherited fromCopy Anchor Link

Envapter.getRequired

getRequiredAll()Copy Anchor Link

static getRequiredAll<Spec, Casing>(spec, casing?): { [K in string | number | symbol as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> };

Read a group of required environment variables in one call. Each key in spec maps to a converter (a token, an array() token, or a custom parser) or a synchronous Standard Schema (zod, valibot, arktype, etc). The returned record holds every value. A converter field is never undefined. A schema field holds whatever its schema returns.

A bad converter in spec throws first. envapt then collects every missing or empty key and throws one MissingEnvValue listing them all. envapt never runs the schema for a missing key, so a schema default such as zod's .default() does not apply here. If no key is missing, envapt reads every field and throws one InvalidEnvValue for all the bad values, schema fields included. Its issues hold every failed field's issues, each with its env key first in path. A converter that cannot convert adds the issue could not be converted. A bad array element and an error a custom parser or schema throws each become an issue carrying their message. The error message lists only the keys, since an issue message can quote the value.

Pass a casing ('camelCase', 'PascalCase', or 'kebab-case') to rename the record keys. The rename splits each key on underscores, as in SCREAMING_SNAKE env-var names. With no casing the keys stay as-is.

Type ParametersCopy Anchor Link

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

{ [K in string | number | symbol as RecaseKey<K & string, Casing>]: InferSpecField<Spec[K]> }

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/required-values

Inherited fromCopy Anchor Link

Envapter.getRequiredAll

has()Copy Anchor Link

static has(key): boolean;

Check whether key has a value. An unset or empty value counts as missing, the same as in getRequired. Under strict mode, a value whose ${VAR} can't resolve counts as missing too, and an ordered key list returns false at that key without checking the later ones.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

boolean

ExampleCopy Anchor Link

const cache = Envapter.has('REDIS_URL') ? createRedisCache() : createMemoryCache();

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/required-values#getrequired-require-and-has

Inherited fromCopy Anchor Link

Envapter.has

require()Copy Anchor Link

static require(...keys): void;

Assert that one or more environment variables are present and non-empty after template resolution. Throws MissingEnvValue listing every missing key. A whitespace-only value counts as missing only under strict mode. Each argument can be an ordered key list, which passes when any of its keys has a value.

For a typed required read in functional code, use Envapter.getRequired(key, converter).

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

ExampleCopy Anchor Link

Envapter.require('DATABASE_URL');
Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');
Envapter.require(['READONLY_URL', 'DATABASE_URL'], 'API_KEY');

Inherited fromCopy Anchor Link

Envapter.require

resetPaths()Copy Anchor Link

static resetPaths(): void;

Clears any Envapter.configureProfiles call, any explicit Envapter.envPaths assignment, and any environment set through Envapter.environment. Envapter.baseDir keeps its value. The call reloads the dotenv-flow cascade right away, choosing the files from the environment set in your env vars.

ReturnsCopy Anchor Link

void

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/env-files#profiles

resolve()Copy Anchor Link

static resolve(strings, ...keys): string;

Tagged template literal for resolving environment variables in template strings. A missing value resolves to an empty string. In strict mode an empty or whitespace-only value throws MissingEnvValue.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string

ExampleCopy Anchor Link

// Given API_HOST=api.example.com and API_PORT=8080 in environment
const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;
// Returns: "Connecting to api.example.com:8080"

// Works with template variables in .env too:
// API_URL=https://${API_HOST}:${API_PORT}
const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;
// Returns: "Service endpoint: https://api.example.com:8080"

// reads READONLY_URL when present, otherwise DATABASE_URL
const db = Envapter.resolve`Connecting to ${['READONLY_URL', 'DATABASE_URL']}`;

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/templates#the-resolve-tagged-template

Inherited fromCopy Anchor Link

Envapter.resolve

useSource()Copy Anchor Link

static useSource(source): void;

Bind the environment Source. On Node the entry binds FileSource for you (a process.env snapshot plus the .env cascade). On the browser or Workers, pass a PortableSource (or any Source) before reading. Pass a (key) => string | undefined reader for a source that reads one key at a time and cannot list its keys. Clears and rebuilds the cache.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void

SeeCopy Anchor Link

https://envapt.materwelon.dev/docs/sources#the-sources-envapt-ships

Inherited fromCopy Anchor Link

Envapter.useSource