Quickstart

Link to section: installInstall

npm install arkenv arktype

Link to section: configure-your-projectConfigure your project

Enable strict mode for the best typesafety:

tsconfig.json

{
  "compilerOptions": {
    "strict": true
  }
}

ArkEnv is built on top of ArkType. Follow the ArkType setup instructions to configure your project.

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 env = 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.

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 dbConfig = {
  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.