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.host", // valid IP address or localhost
  PORT: "number.port", // valid port number (0-65535)
  NODE_ENV: "'development' | 'production' | 'test'",
});

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

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:

ArkEnvError: Errors found while validating environment variables
  HOST must be a string or "localhost" (was missing)
  PORT must be an integer between 0 and 65535 (was "hello")

Features

• Zero external dependencies
• Works in Node.js and Bun
• Tiny: <1kB gzipped
• Build-time and runtime validation
• Single import, zero config for most projects
• Validated, defaultable, typesafe environment variables
• Powered by ArkType, TypeScript's 1:1 validator
• 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 or JetBrains IDEs.

Requirements

• TypeScript >= 5.1 and anything else required by ArkType
• 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".
  • "moduleResolution": "node16" or "nodenext" - For Node.js projects. Supplied by default when using a matching "module" value.
• Tested on Node.js LTS and Current (22 and 25 at the time of this writing, respectively) and Bun 1.2. Older versions may work but are not officially supported

Plugins

• @arkenv/vite-plugin (currently under development) - Vite plugin to validate environment variables at build-time. Requires Vite from 2.9.18 to 7.x.

Supporting ArkEnv

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

You are also welcome to directly contribute to the project's development.

Thanks / Inspiration