options

The second argument to arkenv() is an optional configuration object. Shared fields exist on both engines: env, coerce, emptyAsUndefined, onUndeclaredKey, arrayFormat, and debugSecrets. safe is reserved for call-site compat (false or omit only). toJsonSchema exists only on @arkenv/standard. ArkType already exposes JSON Schema, so @arkenv/core has nothing to fall back to.

Type

ArkEnvConfig is the ArkType engine table. StandardEnvConfig is that table plus optional toJsonSchema.

Options

Each field below is optional. Omit the whole object to read process.env with coercion on.

env

The record to parse. Defaults to process.env. Pass a record in tests, Cloudflare Workers, or when you load values with Vite loadEnv.

import arkenv from "@arkenv/core";

export const env = arkenv(
  { PORT: "number.port" },
  { env: { PORT: "3000" } },
);

coerce

Default: true

When true, ArkEnv turns env strings into the types in your schema before the validator runs. Turn it off when you want raw strings and you transform them yourself.

import arkenv from "@arkenv/core";

export const env = arkenv(
  { PORT: "string" },
  { coerce: false, env: { PORT: "3000" } },
);

env.PORT; // "3000"

See Coercion and parsing.

arrayFormat

Default: "comma"

How ArkEnv parses array env values when coercion is on.

• "comma": split on commas and trim each item
• "json": parse the string as JSON

Use "json" when your host stores arrays as JSON strings.

import arkenv from "@arkenv/core";

export const env = arkenv(
  { TAGS: "string[]" },
  { arrayFormat: "json", env: { TAGS: '["web", "app"]' } },
);

emptyAsUndefined

Default: false

An empty assignment in a .env file still sets the key. ArkEnv sees "", so defaults do not apply and non-string types fail:

PORT=
DEBUG=

Set emptyAsUndefined: true to treat empty strings as missing before validation. Then PORT= behaves like an unset key and the default applies:

import arkenv from "@arkenv/core";

export const env = arkenv(
  {
    PORT: "number.port = 3000",
    DEBUG: "boolean = false",
  },
  {
    emptyAsUndefined: true,
    env: {
      PORT: "",
      DEBUG: "",
    },
  },
);

env.PORT; // 3000
env.DEBUG; // false

The env option above only simulates a loaded .env for the snippet. In an app, your runner or framework loads .env* into process.env first; you pass { emptyAsUndefined: true } alone.

onUndeclaredKey

Default: "delete"

What to do with keys that appear on input but not in your schema.

• "delete": allow them on input, strip them from the output
• "ignore": allow them and keep them on the output
• "reject": fail validation

import arkenv from "@arkenv/core";

export const env = arkenv(
  { PORT: "number.port" },
  {
    onUndeclaredKey: "reject",
    env: { PORT: "3000", EXTRA: "nope" },
  },
);

safe

Default: false

Reserved on the main arkenv() entry. Pass false or omit — { safe: true } is not accepted. For a result object, import arkenv from @arkenv/core/safe or @arkenv/standard/safe.

import arkenv from "@arkenv/core/safe";

const result = arkenv(
  { PORT: "number.port" },
  { env: { PORT: "invalid" } },
);

if (!result.success) {
  console.error(result.issues);
} else {
  console.log(result.data.PORT);
}

debugSecrets

Default: process.env.ARKENV_DEBUG_SECRETS is "true" or "1"

Bypass secret redaction in debug output so you can see raw values. Leave this off in shared logs and CI.

toJsonSchema

@arkenv/standard only. This field is not on ArkType ArkEnvConfig. Vite and Bun /standard plugin configs that alias ParseStandardConfig inherit it.

Pass a fallback converter for Standard Schema validators that omit JSON Schema on the value (Valibot, Zod Mini, Zod v3 via zod-to-json-schema, and similar). ArkEnv calls it per key when it can't read JSON Schema from that value.

Wiring: prefer @arkenv/standard/valibot and @arkenv/standard/zod-mini. The callback remains the escape hatch for Zod v3 and mixed maps. See Coercion.

Framework-only options

Next.js and Nuxt wrappers accept extends to merge shared or client env objects into a server schema. That field lives outside core ArkEnvConfig. See Client vs. server.

Next steps