Zod

@arkenv/standard runs your Zod schemas against the environment. Zod 4.2+ embeds Standard JSON Schema on schema objects, so ArkEnv coerces "3000" and "true" before validation. There is no @arkenv/standard/zod subpath — Classic Zod uses the root import. @arkenv/standard/valibot and @arkenv/standard/zod-mini exist only to bind JSON Schema converters those libraries keep off the value.

For an overview of engine options, see Validators.

Installation

Install @arkenv/standard alongside zod:

npm install @arkenv/standard zod

pnpm add @arkenv/standard zod

yarn add @arkenv/standard zod

bun install @arkenv/standard zod

Define your schema

Declare environment variables in an env.ts file using your standard Zod schemas:

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

export const env = arkenv({
  DATABASE_URL: z.url(),
  PORT: z.int().min(0).max(65535).default(3000),
  DEBUG: z.boolean().default(false),
  TAGS: z.array(z.string()).default([]),
  NODE_ENV: z
    .enum(["development", "production", "test"])
    .default("development"),
});

Because Zod 4.2+ includes JSON Schema metadata, ArkEnv automatically converts "3000" to 3000, "true" to true, and comma-separated lists like "web, api" into string arrays before validation. You can use standard z.number() and z.boolean() directly without manual z.coerce helpers.

Defaults and optionals

Zod methods for defaults and optional fields behave consistently with ArkEnv:

Zod Mini

Zod Mini (import * as z from "zod/mini") omits embedded JSON Schema metadata from schema instances. Import @arkenv/standard/zod-mini so Mini z.number() and z.boolean() coerce without a callback:

import { arkenv } from "@arkenv/standard/zod-mini";
import * as z from "zod/mini";

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

TypeScript must use moduleResolution: "bundler" | "node16" | "nodenext". The root toJsonSchema callback remains available for mixed maps; see Coercion.

Zod v3

Zod v3 (including zod/v3 subpath exports in Zod 4) implements Standard Schema validation but lacks native JSON Schema metadata. You can enable automatic coercion by passing zod-to-json-schema through the toJsonSchema callback:

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",
      }),
  },
);

Use Zod 4.2+ when you can. It ships JSON Schema metadata, so you skip the toJsonSchema callback.

Next steps