ArkEnv

Typesafe environment variables
powered by ArkType

Proud member of the ArkType ecosystem

Read the docs →

Introduction

Tip

📖 Reading this on GitHub? Check out this page in our docs to hover over code blocks and get type hints!

ArkEnv is an environment variable parser powered by ArkType, TypeScript's 1:1 validator. ArkEnv lets you use familiar TypeScript-like syntax to create 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;

With ArkEnv, your environment variables are guaranteed to match your schema. 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)

Features

• Zero external dependencies
• Works in Node.js, Bun, and Vite
• Tiny: <2kB gzipped
• Build-time and runtime validation
• Single import, zero config for most projects
• Validated, defaultable, coerced, typesafe environment variables
• Powered by ArkType, TypeScript's 1:1 validator
• Compatible with any Standard Schema validator (Zod, Valibot, etc.)
• Optimized from editor to runtime

Installation

npm

npm install arkenv arktype

pnpm

pnpm add arkenv arktype

Yarn

yarn add arkenv arktype

Bun

bun add arkenv arktype

🚀 Let's get started! Read the 2-minute setup guide or start with an example.

Tip

Improve your DX with syntax highlighting in VS Code, Cursor, Antigravity, and JetBrains IDEs.

Requirements

ArkEnv is tested on Node.js LTS and Current, Bun 1.3.2, and Vite from 2.9.18 to 7.x. Older versions may work but are not officially supported.

TypeScript setup

While ArkEnv works with plain JavaScript, TypeScript is highly recommended to get the full typesafety benefits. To get ArkEnv to work with TypeScript, we require:

• Modern TypeScript module resolution. One of the following is required in your tsconfig.json:
  • "moduleResolution": "bundler" - Recommended for modern bundlers (Vite, Next.js, etc.). Supplied by default when using "module": "Preserve" (Introduced in TypeScript v5.4).
  • "moduleResolution": "node16" or "nodenext" - For Node.js projects. Supplied by default when using a matching "module" value.
• TypeScript >= 5.1 and anything else required by ArkType

Note

Without TypeScript, runtime validation still works, but you lose build-time type checking and, in some cases, editor autocomplete. Try our examples to see this in action!

Plugins

Beyond the core package, we also provide plugins for frameworks that require a specific implementation to adhere to best practices.

• @arkenv/vite-plugin
• @arkenv/bun-plugin

Supporting ArkEnv

If you love ArkEnv, you can support the project by starring it on GitHub!

You are also welcome to contribute to the project and join the wonderful people who have contributed:

Yam C Borodetsky 💻 💬 🤔 🎨 📖 🐛 💡 🚇 ⚠️

Aruay Berdikulova 💻

David Blass 🤔 🧑‍🏫 💬

Acknowledgements