Valibot

@arkenv/standard/valibot wires Valibot into ArkEnv. Valibot implements Standard Schema. The subpath pre-configures @valibot/to-json-schema so ArkEnv can coerce strings into numbers, booleans, and arrays.

For an overview of engine options, see Validators.

Installation

Install @arkenv/standard, valibot, and the JSON Schema converter (an optional peer of @arkenv/standard):

npm install @arkenv/standard valibot @valibot/to-json-schema

pnpm add @arkenv/standard valibot @valibot/to-json-schema

yarn add @arkenv/standard valibot @valibot/to-json-schema

bun install @arkenv/standard valibot @valibot/to-json-schema

TypeScript must use moduleResolution: "bundler" | "node16" | "nodenext". Subpath exports are not resolved under legacy "node" module resolution.

Define your schema

Declare environment variables in an env.ts file using Valibot schemas:

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

export const env = arkenv({
  DATABASE_URL: v.pipe(v.string(), v.url()),
  PORT: v.optional(v.number(), 3000),
  DEBUG: v.optional(v.boolean(), false),
  TAGS: v.optional(v.array(v.string()), []),
  NODE_ENV: v.optional(
    v.picklist(["development", "production", "test"]),
    "development",
  ),
});

Use v.number() and v.boolean() directly. Manual v.transform(Number) steps are not required.

JSON Schema configuration

Valibot does not embed JSON Schema metadata on schema instances. The /valibot subpath calls @valibot/to-json-schema with:

• typeMode: "input" so piped and transformed schemas are evaluated according to their input types and strings can be coerced
• target: "draft-07" so output matches the JSON Schema draft ArkEnv expects

The root toJsonSchema callback remains available on @arkenv/standard for custom converters or mixed-validator maps. See Coercion.

Defaults and optionals

Valibot fallbacks and optionals map onto ArkEnv the same way as other engines:

Next steps