Valibot

Valibot's v.number() and v.boolean() expect real numbers and booleans. Environment variables arrive as strings, so ArkEnv's @arkenv/standard/valibot entry wires coercion before those schemas run.

Valibot implements Standard Schema. It does not embed JSON Schema on the schema object, so the subpath pre-configures @valibot/to-json-schema. That converter is what lets ArkEnv turn strings into numbers, booleans, and arrays.

How the two engines differ is in Validators.

Installation

Install @arkenv/standard, valibot, and the JSON Schema converter. The converter is an optional peer of @arkenv/standard. The /valibot entry imports it, so this path needs the package installed.

npm 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

Put Valibot schemas in env.ts and import arkenv from @arkenv/standard/valibot, not the root @arkenv/standard entry. The root import does not bind Valibot's JSON Schema converter, so numbers and booleans stay strings.

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