Schema Validation

EnvManager supports schema validation to ensure your environment variables have correct types and values. Define schemas in the web UI or local JSON files, then validate with the CLI.

The validate Command

envmanager validate [options]

Options:

Validate Against EnvManager Schema

If you've defined a schema in the EnvManager web UI:

envmanager validate

Output:

Validation Results
File: .env
Variables: 12
Schema fields: 10

Errors (2):
  - PORT: Expected number, got "not_a_number"
  - LOG_LEVEL: Must be one of: debug, info, warn, error

Warnings (2):
  - EXTRA_VAR: Not defined in schema
  - OLD_VAR: Not defined in schema

Validation failed

Validate Against Local Schema

For projects without EnvManager schema or offline validation:

envmanager validate --schema schema.json

Schema Format

Schemas are JSON objects defining validation rules for each variable:

{
  "PORT": {
    "type": "number",
    "required": true,
    "min": 1,
    "max": 65535
  },
  "DATABASE_URL": {
    "type": "string",
    "required": true,
    "pattern": "^postgres://"
  },
  "LOG_LEVEL": {
    "type": "string",
    "enum": ["debug", "info", "warn", "error"],
    "default": "info"
  },
  "ENABLE_CACHE": {
    "type": "boolean",
    "default": "true"
  },
  "API_TIMEOUT": {
    "type": "number",
    "min": 1000,
    "max": 30000
  }
}

Schema Fields

Type Validation

string: Any text value

{ "API_KEY": { "type": "string", "required": true } }

number: Numeric values (integers or decimals)

{ "PORT": { "type": "number", "min": 1, "max": 65535 } }

boolean: true or false (case-insensitive)

{ "DEBUG": { "type": "boolean", "default": "false" } }

url: Valid URL format

{ "API_URL": { "type": "url", "required": true } }

email: Valid email format

{ "ADMIN_EMAIL": { "type": "email", "required": true } }

Strict Mode

By default, extra variables not in the schema produce warnings but don't fail validation. Use --strict to fail on warnings:

envmanager validate --strict

This is useful in CI/CD to catch accidental variables.

Runtime Validation Package

For validating environment variables at application startup, use the @envmanager/validate package:

npm install @envmanager/validate

Usage

import { validateEnv, z } from '@envmanager/validate'

// Define schema using Zod
const schema = {
  PORT: z.coerce.number().min(1).max(65535),
  DATABASE_URL: z.string().url(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
  ENABLE_CACHE: z.coerce.boolean().default(true),
}

// Validate and get typed environment
const env = validateEnv(schema)

// env is fully typed:
// env.PORT: number
// env.DATABASE_URL: string
// env.LOG_LEVEL: 'debug' | 'info' | 'warn' | 'error'
// env.ENABLE_CACHE: boolean

Error Handling

try {
  const env = validateEnv(schema)
} catch (error) {
  if (error instanceof EnvValidationError) {
    console.error('Invalid environment:')
    error.errors.forEach(e => {
      console.error(`  ${e.key}: ${e.message}`)
    })
    process.exit(1)
  }
}

Generating Zod Schema from JSON

import { createZodSchema } from '@envmanager/validate'
import schemaJson from './schema.json'

const zodSchema = createZodSchema(schemaJson)
const env = validateEnv(zodSchema)

Web UI Schema Editor

Define schemas visually in the EnvManager web UI:

1. Go to your project
2. Click the Schema tab
3. Add variables and set their types/constraints
4. Save the schema

The schema is then available for CLI validation and runtime validation.

CI/CD Integration

Add validation to your deployment pipeline:

# GitHub Actions
- name: Validate environment
  run: envmanager validate --strict
  env:
    ENVMANAGER_API_KEY: ${{ secrets.ENVMANAGER_API_KEY }}

# GitLab CI
validate-env:
  script:
    - envmanager validate --strict
  variables:
    ENVMANAGER_API_KEY: $ENVMANAGER_API_KEY

Best Practices

1. Always validate in CI: Catch configuration errors before deployment
2. Use strict mode in production pipelines: Extra variables often indicate issues
3. Define schemas early: Set up validation when creating new projects
4. Keep schemas in sync: Use envmanager template generate after schema changes
5. Validate at runtime: Use @envmanager/validate for type-safe environment access