Quickstart

Link to section: installInstall

npm install arkenv arktype

Link to section: configure-your-projectConfigure your project

Enable strict mode for the best typesafety, and use a modern TypeScript module resolution:

tsconfig.json

{
  "compilerOptions": {
    "strict": true, 
    "moduleResolution": "bundler" // or "node16" / "nodenext"
  }
}

Tip

You may omit moduleResolution if module is "Preserve", "Node16", or "NodeNext". See Requirements for details.

ArkEnv is built on top of ArkType. Follow the ArkType setup to complete your configuration.

Link to section: define-the-schemaDefine the schema

Add a schema to make your environment variables validated and typesafe:

config/env.ts

import arkenv, { type } from 'arkenv';

export const  = arkenv({
  // Built-in validators
  DATABASE_HOST: "string.host",
  DATABASE_PORT: "number.port",
  
  // Boolean values (accepts "true"/"false" strings, converts to boolean)
  DEBUG: "boolean",
  
  // Custom string literals
  NODE_ENV: "'development' | 'production' | 'test'",
  
  // Optional variables with defaults
  LOG_LEVEL: "'debug' | 'info' | 'warn' | 'error' = 'info'",
  
  // Array defaults using type function
  ALLOWED_ORIGINS: type("string[]").default(() => ["localhost"]),
  FEATURE_FLAGS: type("string[]").default(() => []),
  
  // Optional environment variable
  "API_KEY?": 'string'
});

Tip

Improve your DX with syntax highlighting in VS Code & Cursor or JetBrains IDEs.

Note

Need complex validation? ArkEnv also works with any Standard Schema validator like Zod or Valibot alongside ArkType!

Link to section: define-environment-variablesDefine environment variables

Create a .env file in your project root with some environment variables:

.env

DATABASE_HOST=localhost
DATABASE_PORT=5432
DEBUG=true
NODE_ENV=development
API_KEY=your-secret-key

Tip

Avoid committing your .env file to version control:

echo ".env" >> .gitignore

Link to section: use-in-your-codeUse in your code

Import and use your validated and typed environment variables. Here is an example for a database configuration file:

database.ts

import { env } from './config/env';

// Hover to see your validated config
const  = {
  host: env.DATABASE_HOST,
  port: env.DATABASE_PORT,
};

Now you might start to see the magic of ArkType and TypeScript working together to make your environment variables more reliable, more readable, and more typesafe.