Standard Env

Type-safe, structured environment variable parsing using Standard Schema compatible validation libraries.

Features

🔒 Type-safe - Full TypeScript support with automatic type inference
🏗️ Structured config - Organize environment variables into nested objects
🚀 Declarative API - Define your config structure in a single object
🔄 Library agnostic - Works with any Standard Schema compatible library (arktype, zod, valibot, etc.)
🎯 Default values & optional properties - Flexible configuration with type safety
📦 Zero runtime dependencies - Lightweight and focused

Installation

bun add standardenv

# Also install your preferred validation library
bun add arktype  # or zod, valibot, etc.

Quick Start

import { envParse } from "standardenv";
import { type } from "arktype";

const config = envParse(process.env, {
  server: {
    port: {
      format: type('string.numeric.parse'),
      default: 3000,
      env: 'PORT'
    },
    nodeEnv: {
      format: type('"development" | "production" | "test"'),
      default: 'development',
      env: 'NODE_ENV'
    }
  },
  db: {
    url: {
      format: type('string'),
      env: 'DATABASE_URL'
    }
  }
});

// config.server.port is number (3000)
// config.server.nodeEnv is string ('development' | 'production' | 'test')
// config.db.url is string
// All fully typed with zero additional type definitions needed! ✨

Core Concepts

Declarative Configuration

Instead of separate schemas and defaults, define everything in one place:

const config = envParse(process.env, {
  // Nested structure for organization
  db: {
    url: {
      format: type('string'),           // Validation schema
      env: 'DATABASE_URL',             // Environment variable name
      // Required by default (no default provided)
    },
    maxConnections: {
      format: type('string.numeric.parse'),
      default: 10,                   // Default value
      env: 'DB_MAX_CONNECTIONS',
    }
  },

  server: {
    port: {
      format: type('string.numeric.parse'),
      default: 3000,
      env: 'PORT',
    },
    debug: {
      format: type('string').pipe(s => s === 'true'),
      default: false,
      env: 'DEBUG',
    }
  }
});

Property Configuration

Each property has these fields:

format: StandardSchema validator (required)
env: Environment variable name (required)
default: Default value (optional)
optional: If true, property can be undefined (optional)

Optional Properties

Mark properties as optional when they might not be set:

const config = envParse(process.env, {
  db: {
    url: {
      format: type('string'),
      env: 'DATABASE_URL', // Required - will throw if missing
    },
    redis: {
      url: {
        format: type('string'),
        env: 'REDIS_URL',
        optional: true, // Optional - will be undefined if not set
      }
    }
  },
  features: {
    analytics: {
      format: type('string').pipe(s => s === 'true'),
      env: 'ENABLE_ANALYTICS',
      optional: true, // Optional - will be undefined if not set
    }
  }
});

// TypeScript knows:
// config.db.url: string (required)
// config.db.redis.url: string | undefined (optional)
// config.features.analytics: boolean | undefined (optional)

Type Transformations

Environment variables are strings, but you often need other types:

Common Transformations with arktype

import { envParse } from "standardenv";
import { type } from "arktype";

const config = envParse(process.env, {
  server: {
    // String to number
    port: {
      format: type('string.numeric.parse'),
      default: 3000,
      env: 'PORT',
    },

    // String to boolean
    debug: {
      format: type('string').pipe(s => s === 'true' || s === '1'),
      default: false,
      env: 'DEBUG',
    },

    // String to array
    allowedOrigins: {
      format: type('string').pipe(s => s.split(',').map(origin => origin.trim())),
      default: ['http://localhost:3000'],
      env: 'ALLOWED_ORIGINS',
    },

    // String to JSON object
    featureFlags: {
      format: type('string').pipe((s): Record<string, boolean> => {
        try {
          return JSON.parse(s);
        } catch {
          return {};
        }
      }),
      default: {},
      env: 'FEATURE_FLAGS',
    }
  }
});

// Result types:
// config.server.port: number
// config.server.debug: boolean
// config.server.allowedOrigins: string[]
// config.server.featureFlags: Record<string, boolean>

Deeply Nested Configuration

Organize complex applications with deep nesting:

const config = envParse(process.env, {
  database: {
    primary: {
      url: {
        format: type('string'),
        env: 'DATABASE_URL',
      },
      maxConnections: {
        format: type('string.numeric.parse'),
        default: 20,
        env: 'DB_MAX_CONNECTIONS',
      }
    },
    cache: {
      redis: {
        url: {
          format: type('string'),
          env: 'REDIS_URL',
          optional: true,
        },
        ttl: {
          format: type('string.numeric.parse'),
          default: 3600,
          env: 'CACHE_TTL',
        }
      }
    }
  },

  auth: {
    jwt: {
      secret: {
        format: type('string'),
        env: 'JWT_SECRET',
      },
      expiresIn: {
        format: type('string'),
        default: '7d',
        env: 'JWT_EXPIRES_IN',
      }
    },
    oauth: {
      providers: {
        format: type('string').pipe(s => s.split(',')),
        default: ['google', 'github'],
        env: 'OAUTH_PROVIDERS',
      }
    }
  },

  logging: {
    level: {
      format: type('"debug" | "info" | "warn" | "error"'),
      default: 'info',
      env: 'LOG_LEVEL',
    },
    destination: {
      format: type('string'),
      default: 'console',
      env: 'LOG_DESTINATION',
      optional: true,
    }
  }
});

// Access with clean, organized structure:
// config.database.primary.url
// config.database.cache.redis.url
// config.auth.jwt.secret
// config.auth.oauth.providers
// config.logging.level

Library Compatibility

Works with any Standard Schema compatible library:

Arktype

import { type } from "arktype";

const config = envParse(process.env, {
  port: {
    format: type('string.numeric.parse'),
    env: 'PORT',
  }
});

Zod

import { z } from "zod";

const config = envParse(process.env, {
  port: {
    format: z.string().transform(Number),
    env: 'PORT',
  }
});

Valibot

import * as v from "valibot";

const config = envParse(process.env, {
  port: {
    format: v.pipe(v.string(), v.transform(Number)),
    env: 'PORT',
  }
});

Error Handling

Get clear error messages for validation failures:

import { EnvValidationError } from "standardenv";

try {
  const config = envParse(process.env, {
    port: {
      format: type('string.numeric.parse'),
      env: 'PORT', // Required, no default
    }
  });
} catch (error) {
  if (error instanceof EnvValidationError) {
    console.error("Environment validation failed:", error.message);
    console.error("Issues:", error.issues);
    console.error("Validator:", error.vendor);
  }
}

API Reference

`envParse(env, config)`

env: Record<string, string | undefined> - Environment variables (typically process.env)
config: ConfigDefinition - Declarative configuration structure

Returns the validated and typed configuration object with inferred types.

Configuration Properties

Each property in your config can have:

format (required): StandardSchema validator for the environment variable
env (required): Environment variable name to read from
default (optional): Default value (must be string - will be validated by format)
optional (optional): If true, property will be T | undefined instead of T

Error Classes

EnvValidationError - Thrown when environment variables fail validation
AsyncValidationError - Thrown when async validation is attempted (not supported)

Best Practices

✅ Do

// Organize related config into nested objects
const config = envParse(process.env, {
  database: {
    url: { format: type('string'), env: 'DATABASE_URL' },
    poolSize: { format: type('string.numeric.parse'), default: 10, env: 'DB_POOL_SIZE' }
  }
});

// Use meaningful default values
const config = envParse(process.env, {
  server: {
    port: { format: type('string.numeric.parse'), default: 3000, env: 'PORT' }
  }
});

// Mark truly optional config as optional
const config = envParse(process.env, {
  monitoring: {
    sentryDsn: { format: type('string'), env: 'SENTRY_DSN', optional: true }
  }
});

❌ Don't

// Don't use non-string types in format without transformation
const config = envParse(process.env, {
  port: { format: type('number'), env: 'PORT' } // ❌ Will fail - env vars are strings
});

// Don't put defaults that don't match the expected format
const config = envParse(process.env, {
  port: { format: type('string.numeric.parse'), default: '3000', env: 'PORT' } // ❌ Default should be number
});

Complete Example

import { envParse } from "standardenv";
import { type } from "arktype";

export const config = envParse(process.env, {
  app: {
    name: {
      format: type('string'),
      default: 'my-app',
      env: 'APP_NAME',
    },
    version: {
      format: type('string'),
      default: '1.0.0',
      env: 'APP_VERSION',
    }
  },

  server: {
    port: {
      format: type('string.numeric.parse'),
      default: 3000,
      env: 'PORT',
    },
    host: {
      format: type('string'),
      default: '0.0.0.0',
      env: 'HOST',
    },
    cors: {
      origins: {
        format: type('string').pipe(s => s.split(',').map(o => o.trim())),
        default: ['http://localhost:3000'],
        env: 'CORS_ORIGINS',
      }
    }
  },

  database: {
    url: {
      format: type('string'),
      env: 'DATABASE_URL',
    },
    ssl: {
      format: type('string').pipe(s => s === 'true'),
      default: false,
      env: 'DATABASE_SSL',
    }
  },

  auth: {
    clerk: {
      secretKey: {
        format: type('string'),
        env: 'CLERK_SECRET_KEY',
      },
      publishableKey: {
        format: type('string'),
        env: 'CLERK_PUBLISHABLE_KEY',
      }
    }
  },

  features: {
    analytics: {
      format: type('string').pipe(s => s === 'true'),
      default: false,
      env: 'ENABLE_ANALYTICS',
    },
    monitoring: {
      format: type('string').pipe(s => s === 'true'),
      default: false,
      env: 'ENABLE_MONITORING',
      optional: true,
    }
  }
});

// config is fully typed as:
// {
//   app: { name: string; version: string };
//   server: { port: number; host: string; cors: { origins: string[] } };
//   database: { url: string; ssl: boolean };
//   auth: { clerk: { secretKey: string; publishableKey: string } };
//   features: { analytics: boolean; monitoring?: boolean };
// }

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
src		src
test		test
.gitignore		.gitignore
.oxlintrc.json		.oxlintrc.json
AGENTS.md		AGENTS.md
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Standard Env

Features

Installation

Quick Start

Core Concepts

Declarative Configuration

Property Configuration

Optional Properties

Type Transformations

Common Transformations with arktype

Deeply Nested Configuration

Library Compatibility

Arktype

Zod

Valibot

Error Handling

API Reference

`envParse(env, config)`

Configuration Properties

Error Classes

Best Practices

✅ Do

❌ Don't

Complete Example

About

Uh oh!

Releases

Packages

Uh oh!

Languages

alandotcom/standard-env

Folders and files

Latest commit

History

Repository files navigation

Standard Env

Features

Installation

Quick Start

Core Concepts

Declarative Configuration

Property Configuration

Optional Properties

Type Transformations

Common Transformations with arktype

Deeply Nested Configuration

Library Compatibility

Arktype

Zod

Valibot

Error Handling

API Reference

envParse(env, config)

Configuration Properties

Error Classes

Best Practices

✅ Do

❌ Don't

Complete Example

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`envParse(env, config)`

Packages