Introduction

What is ArkEnv?

ArkEnv is a typesafe environment variable validation library for TypeScript. You declare a schema once, arkenv() validates the process against that schema before application code runs, and TypeScript infers the types from the same declaration.

This page shows why process.env is a weak contract, how ArkEnv's typed env object replaces it, and where to go next in these docs.

The `process.env` problem

Environment variables arrive as process.env (or import.meta.env), where all values are string | undefined. Most teams start with a presence-check helper that verifies required keys:

.env

PORT=3000
DEBUG=false

./env.ts

export function () {
  const  = process..;
  const  = process..;

  if ( ===  ||  === ) {
    throw new Error("Missing required environment variables");
  }

  return { ,  };
}

For presence-only strings, this helper installs nothing and gets the job done. But it breaks when variables need types and coercion:

Booleans (DEBUG=false): process.env.DEBUG is the string "false". The presence check passes and returns { debug: "false" }. Because non-empty strings are truthy in JavaScript, if (debug) runs even when set to false.
Numbers (PORT=3000): port remains a string. Arithmetic like port + 1 evaluates to "30001", and comparisons like port > 1024 perform lexicographical checks rather than numeric ones.

ArkEnv replaces manual presence checks and ad-hoc parsing with declarative schema validation and zero-config coercion.

The `env` solution

ArkEnv solves the environment variable scaling problem. Declare a schema in env.ts; arkenv() validates against it so application code never touches loose process.env:

./env.ts

import  from "@arkenv/core";

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

The same if as above, after ArkEnv:

./server.ts

import {  } from "./env";

const  = .PORT;
const debug = .DEBUG;      
const debug: boolean

if () {
  console.log("verbose logging enabled");
}

console.log(`listening on ${}`);

Everything works like our manual solution, but the parsing logic is written declaratively in a single file. This makes the code simpler and more maintainable.

In a full-stack app, we must keep secrets off the client. The Next.js, Nuxt, Vite, and Bun packages enforce that split. See Client vs. server.

ArkType, Zod, and Valibot are first-class. Use @arkenv/core for ArkType, or @arkenv/standard for Zod and Valibot (and any other Standard Schema validator). See the Zod and Valibot guides.

How to use these docs

Start with Getting started to add ArkEnv to a new or existing project. Core concepts covers the schema, the typed env object, engines, and coercion. Some other useful reads: