Options
Configuration options
These apply to the arkenv() function imported from either arkenv or arkenv/standard.
Prop
Type
The environment variables to parse. Defaults to process.env.
All values must be strings (or undefined) to match process.env semantics.
Type
Record<string, string | undefined> | undefined
Whether to coerce environment variables to their defined types. Defaults to true
Type
boolean | undefined
Control how ArkEnv handles environment variables that are not defined in your schema.
Defaults to 'delete' to ensure your output object only contains
keys you've explicitly declared. This differs from ArkType's standard behavior, which
mirrors TypeScript by defaulting to 'ignore'.
delete(ArkEnv default): Undeclared keys are allowed on input but stripped from the output.ignore(ArkType default): Undeclared keys are allowed and preserved in the output.reject: Undeclared keys will cause validation to fail.
Type
"ignore" | "delete" | "reject" | undefined
Default
"delete"
The format to use for array parsing when coercion is enabled.
comma(default): Strings are split by comma and trimmed.json: Strings are parsed as JSON.
Type
"comma" | "json" | undefined
Default
"comma"
Whether to treat empty strings ("") as undefined before validation.
When enabled, an environment variable set to an empty value (e.g. PORT=)
will be treated as if it were missing, allowing defaults to apply and
preventing validation errors for numeric or boolean types.
Type
boolean | undefined
Default
false
Examples
Custom env source
You can pass a custom object instead of process.env. This is particularly useful in environments like Cloudflare Workers where variables are passed via a context object, or when testing.
const = (
{ : "number" },
{ : { : "3000" } }
);Disabling coercion
By default, ArkEnv automatically coerces string environment variables to numbers or booleans if the schema requires it. You can disable this behavior:
const = (
{ : "number" },
{ : false }
);See the coercion docs for more details.
Custom array format
When coercion is enabled, you can specify how array strings are parsed.
const = (
{ : "string[]" },
{ : "json", : { : '["web", "app"]' } }
);Empty strings as undefined
When emptyAsUndefined is enabled, an environment variable set to an empty value (e.g., PORT= in a .env file) will be treated as if it were missing. This allows defaults to apply and prevents validation errors for numeric or boolean types.
const = (
{
: "number = 3000",
: "boolean = false",
},
{
: true,
: {
: "",
: "",
},
}
);
// env.PORT → 3000 (default applied)
// env.DEBUG → false (default applied)