What is ArkEnv?

At its core, ArkEnv is a single export that creates a ready-to-use, typesafe environment variable object:

import arkenv from "arkenv";

const env = arkenv({
  HOST: "string.ip | 'localhost'",
  PORT: "0 <= number.integer <= 65535",
  NODE_ENV: "'development' | 'production' | 'test' = 'development'",
  DEBUGGING: "boolean = false",
});

// Hover to see ✨exact✨ types
const host = env.HOST;
const port = env.PORT;
const nodeEnv = env.NODE_ENV;
const debugging = env.DEBUGGING;

ArkEnv defaults to ArkType notation, the closest match to TypeScript syntax for editor-to-runtime typesafety. You can also use any Standard Schema validator, including Zod, Valibot, and Typia.

We consider the resulting env object "typesafe from editor to runtime": at every step in the app's lifecycle, you are getting a guarantee about your environment variables.

Link to section: editor#Editor

ArkEnv tells TypeScript about the shape of your environment variables, so you can use the types your schema defines without additional checks or manual type-casts. Your editor will also autocomplete your schema and provide type hints, whether you're using ArkType, Zod, Valibot, or any other Standard Schema validator. If you're using ArkType, you can take this a step further with syntax highlighting and inline errors. This way, writing your schema feels like writing TypeScript.

Link to section: build-time#Build time

Wherever possible, ArkEnv is designed to run during your build process. We provide a toolkit for doing so with Bun's bundler and Vite. This way, your app will fail fast if any environment variables are incorrect or missing.

Link to section: runtime#Runtime

With ArkEnv, your environment variables are guaranteed to match your schema at runtime. If any variable is incorrect or missing, the app won't start and a clear error will be thrown:

❯ PORT=hello npm start

ArkEnvError: Errors found while validating environment variables
  HOST must be a string or "localhost" (was missing)
  PORT must be a number (was a string)

Link to section: features#Features

• Zero external dependencies
• Works in Node.js, Bun, and Vite
• Tiny: <2kB gzipped
• Build-time / runtime validation with editor autocomplete & type hints
• Single import, zero config for most projects
• Optional variables and default values
• Intuitive automatic coercion
• Compatible with any Standard Schema validator (Zod, Valibot, etc.)
• Native support for ArkType, TypeScript’s 1
  validator

See how ArkEnv compares to alternatives like T3 Env, znv, and envalid in the comparison cheatsheet.

Link to section: philosophy#Philosophy

Link to section: build-from-the-core-up#Build from the core up

Some environment variable validators were built around a specific framework and its conventions. ArkEnv, instead, is designed to "just work" even within a simple Node.js server, with no configuration required. This core is where ArkEnv started, and it's what we continue to test and optimize today.

We layer framework integrations as optional modules (which we call "plugins") on top of this core to provide a convenient experience for your app's development. Using these integrations in modern JavaScript toolkits should feel just as simple as using the core library within a simple Node.js server.

Link to section: fail-fast#Fail fast

ArkEnv is built to protect your app from runtime errors as early as possible. This means that as soon as we know what the actual values are, we'll fail your app if they don't match your schema. When environment variables eventually reach runtime, you can be sure they're valid.

Link to section: sane-defaults#Sane defaults

ArkEnv makes a few opinionated assumptions about your workflow:

• Environment variables come from process.env (or import.meta.env in Vite)
• They start as strings but should become the types defined in your schema
• Your framework already loads .env files
• You're using a modern, Standard Schema-compliant validator

These defaults keep ArkEnv dead simple. If your workflow is different, you can opt out of features like type coercion, customize the env source, or extend behavior with plugins.

Link to section: next-steps#Next steps