Coercion and parsing

Environment variables arrive as strings. ArkEnv coerces those strings toward the types your schema declares so application code can treat PORT as a number and DEBUG as a boolean.

The same coerce option and pre-coercion pipeline apply to @arkenv/core and @arkenv/standard.

Defaults

Coercion is on by default (coerce: true). Zod 4.2+ uses z.number() and z.boolean() here; ArkEnv converts "8080" and "true" before the schema runs.

import arkenv from "@arkenv/core";

export const env = arkenv(
  {
    PORT: "number.port",
    DEBUG: "boolean = false",
    TAGS: "string[]",
  },
  {
    env: {
      PORT: "8080",
      DEBUG: "true",
      TAGS: "web, api",
    },
  },
);

env.PORT; // number
env.DEBUG; // boolean
env.TAGS; // string[]

import arkenv from "@arkenv/standard";
import * as z from "zod";

export const env = arkenv(
  {
    PORT: z.int().min(0).max(65535),
    DEBUG: z.boolean().default(false),
    TAGS: z.array(z.string()),
  },
  {
    env: {
      PORT: "8080",
      DEBUG: "true",
      TAGS: "web, api",
    },
  },
);

env.PORT; // number
env.DEBUG; // boolean
env.TAGS; // string[]

Numbers

Any field typed as number or a numeric subtype (including number.port) is parsed from the string form:

import arkenv from "@arkenv/core";

export const env = arkenv(
  {
    PORT: "number.port",
    RETRY_COUNT: "number.integer = 3",
    AGE: "0 <= number.integer <= 120",
  },
  {
    env: {
      PORT: "8080",
      RETRY_COUNT: "5",
      AGE: "30",
    },
  },
);

env.PORT;
const env: {
    PORT: number;
    RETRY_COUNT: number;
    AGE: number;
}

Booleans

boolean accepts the lowercase strings "true" and "false" only. Values like "0", "1", "True", "YES", or "on" are not coerced and fail validation.

import arkenv from "@arkenv/core";

export const env = arkenv(
  { DEBUG: "boolean = false" },
  { env: { DEBUG: "true" } },
);

env.DEBUG;
const env: {
    DEBUG: boolean;
}

Need a wider truthy set? Normalize with a transform (ArkType morph or Zod/Valibot .transform), or keep the field as string and map it in application code.

Arrays

By default ArkEnv splits on commas and trims each entry:

import arkenv from "@arkenv/core";

export const env = arkenv(
  {
    TAGS: "string[]",
    PORTS: "number[]",
  },
  {
    env: {
      TAGS: "web, app, api",
      PORTS: "3000, 8080",
    },
  },
);

env.TAGS;
const env: {
    TAGS: string[];
    PORTS: number[];
}
env.PORTS;
const env: {
    TAGS: string[];
    PORTS: number[];
}

Switch to JSON arrays with arrayFormat: "json":

import arkenv from "@arkenv/core";

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

env.TAGS;
const env: {
    TAGS: string[];
}

Objects

JSON strings map onto nested object schemas. Nested fields are coerced too:

import arkenv from "@arkenv/core";

export const env = arkenv(
  {
    DATABASE: {
      HOST: "string",
      PORT: "number",
    },
  },
  {
    env: {
      DATABASE: '{"HOST": "localhost", "PORT": "5432"}',
    },
  },
);

env.DATABASE;
const env: {
    DATABASE: {
        HOST: string;
        PORT: number;
    };
}

Pre-coercion model

ArkEnv does not wrap your schema in a coercion pipe. It uses a shared pre-coercion pipeline for both engines:

1. Introspect the schema's JSON Schema (ArkType .in.toJsonSchema, or Standard Schema metadata / optional toJsonSchema fallback)
2. Find paths that need conversion (numbers, booleans, arrays, objects)
3. Copy the input record and coerce only those paths on the copy
4. Validate the copy with the original, unmodified schema

process.env is never mutated. Schema transforms and refinements still see the coerced values.

Transforms

A transform reshapes a value after it is a valid input: trim a string, clamp a number, map an enum. Schema libraries call these transforms, morphs, or pipes. ArkEnv runs them as part of parsing.

PORT still uses built-in coercion, not a custom pipe:

import arkenv, { type } from "@arkenv/core";

export const env = arkenv(
  {
    BUILD_ID: type("string").pipe((value) => value.trim().toUpperCase()),
    PORT: "number.port = 3000",
  },
  { env: { BUILD_ID: "  abc  " } },
);

env.BUILD_ID; // "ABC"

import arkenv from "@arkenv/standard";
import * as z from "zod";

export const env = arkenv(
  {
    BUILD_ID: z
      .string()
      .transform((value) => value.trim().toUpperCase()),
    PORT: z.int().min(0).max(65535).default(3000),
  },
  { env: { BUILD_ID: "  abc  " } },
);

env.BUILD_ID; // "ABC"

Coercion can feed a transformation. The string "3" becomes a number before your pipe runs:

import arkenv, { type } from "@arkenv/core";

export const env = arkenv(
  {
    RETRY_COUNT: type("number").pipe((n) => Math.max(0, n)),
  },
  { env: { RETRY_COUNT: "3" } },
);

env.RETRY_COUNT; // 3

import arkenv from "@arkenv/standard";
import * as z from "zod";

export const env = arkenv(
  {
    RETRY_COUNT: z.number().transform((n) => Math.max(0, n)),
  },
  { env: { RETRY_COUNT: "3" } },
);

env.RETRY_COUNT; // 3

Valibot (toJsonSchema)

Prefer @arkenv/standard/valibot so @valibot/to-json-schema is bound for you (typeMode: "input", target: "draft-07"):

import { arkenv } from "@arkenv/standard/valibot";
import * as v from "valibot";

export const env = arkenv({ PORT: v.number(), DEBUG: v.boolean() });

Install @valibot/to-json-schema yourself; it is an optional peer of @arkenv/standard. Recipe: Valibot.

The optional toJsonSchema callback on root @arkenv/standard remains the escape hatch for custom converters. ArkEnv calls it when it can't read JSON Schema from that key:

import arkenv from "@arkenv/standard";
import * as v from "valibot";
import { toJsonSchema } from "@valibot/to-json-schema";

export const env = arkenv(
  { PORT: v.number(), DEBUG: v.boolean() },
  {
    toJsonSchema: (schema) =>
      toJsonSchema(schema as v.GenericSchema, {
        typeMode: "input",
        target: "draft-07",
      }),
  },
);

• target: "draft-07" matches the JSON Schema draft ArkEnv expects.
• typeMode: "input" coerces env strings toward the schema's input type. A bare { toJsonSchema } function reference uses Valibot's default typeMode: "ignore".
• Valibot's converter does not accept Standard Schema, so assert as v.GenericSchema at the call.

Zod v3

Same escape hatch: Zod v3 validates via Standard Schema but omits Standard JSON Schema on the value. Convert with zod-to-json-schema (works with zod@3 or Zod 4's zod/v3 export):

import arkenv from "@arkenv/standard";
import { z } from "zod/v3";
import { zodToJsonSchema } from "zod-to-json-schema";

export const env = arkenv(
  { PORT: z.number(), DEBUG: z.boolean() },
  {
    toJsonSchema: (schema) =>
      zodToJsonSchema(schema as z.ZodTypeAny, {
        $refStrategy: "none",
      }),
  },
);

Recipe: Zod.

Mixing with Zod Mini

Prefer @arkenv/standard/zod-mini for Mini-only maps. Mini has no ~standard.jsonSchema and no instance .toJSONSchema(). When you mix Valibot and Mini on root @arkenv/standard, switch on schema["~standard"].vendor and return undefined for anything else. Mini reports vendor "zod". Classic Zod keys never reach the callback at runtime.

import arkenv from "@arkenv/standard";
import { toJsonSchema } from "@valibot/to-json-schema";
import * as v from "valibot";
import * as z from "zod/mini";

export const env = arkenv(
  {
    PORT: v.number(),
    DEBUG: z.boolean(),
  },
  {
    toJsonSchema: (schema) => {
      switch (schema["~standard"].vendor) {
        case "valibot":
          return toJsonSchema(schema as v.GenericSchema, {
            typeMode: "input",
            target: "draft-07",
          });
        case "zod":
          return z.toJSONSchema(schema as z.ZodMiniType, {
            io: "input",
            target: "draft-07",
          });
        default:
          return undefined;
      }
    },
  },
);

Disabling coercion

Turn the pipeline off when a field must stay a string, or when you want the schema library to parse it.

import arkenv from "@arkenv/core";

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

env.PORT; // string

import arkenv from "@arkenv/standard";
import * as z from "zod";

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

env.PORT; // string

With coerce: false, a numeric schema rejects "3000" unless you transform the string yourself (or use a helper such as z.coerce.number()).

Next steps