Skip to content
BranchesTags

Repository files navigation

Envase

Type-safe environment variable validation with Standard Schema compliance. Works with Zod, Valibot, ArkType, and other Standard Schema-compatible validation libraries.

"Envase" is Spanish for "container" - reflecting how this library encapsulates environment variables in a safe, structured, and validated way.

Highlights

  • 🔒 Type-safe validation - Full TypeScript type inference
  • 🔌 Standard Schema compliant - Works with any compatible validation library
  • 🌐 Runtime agnostic - Runs anywhere (Node, Bun, Deno, browsers)
  • 🏗️ Structured configuration - Supports nested config objects
  • 🧮 Computed values - Derive values from parsed config with full type inference
  • 🚦 Environment detection - isProduction, isTest, isDevelopment flags
  • 📜 Detailed error reporting - See all validation failures at once
  • 🙈 Sensitive values - Keep secrets out of validation errors
  • 🚀 Lightweight - No runtime dependencies (CLI-only deps aside)

Installation

npm install envase

Note: This package is ESM-only. It does not support CommonJS require(...).

Validation Library Support

Built on the Standard Schema specification, Envase works seamlessly with any schema library that implements the spec. The CLI documentation generator additionally requires Standard JSON Schema support to introspect and document your schemas.

See the full list of compatible libraries: Standard Schema | Standard JSON Schema.

Popular options include:

  • Zod - v3.24+ (Standard Schema), v4.2+ (JSON Schema)
  • Valibot - v1.0+ (Standard Schema), v1.2+ (JSON Schema via @valibot/to-json-schema)
  • ArkType - v2.0+ (Standard Schema), v2.1.28+ (JSON Schema)

Key features

Type-Safe Validation of Nested Schema

import { parseEnv, envvar } from 'envase';
import { z } from 'zod';

const envSchema = {
  app: {
    listen: {
      port: envvar('PORT', z.coerce.number().int().min(0).max(65535)),
    },
  },
  db: {
    host: envvar('DB_HOST', z.string().min(1).default('localhost')),
  },
  apiKey: envvar('API_KEY', z.string().min(32).optional()),
};

const config = parseEnv(process.env, envSchema)
// config.app.listen.port -> number
// config.db.host -> string
// config.apiKey -> string | undefined

Environment Detection

import { detectNodeEnv } from 'envase';

const nodeEnv = detectNodeEnv(process.env);
// nodeEnv.isProduction -> boolean
// nodeEnv.isTest -> boolean
// nodeEnv.isDevelopment -> boolean

These flags are inferred from the NODE_ENV value (i.e. 'production', 'test', or 'development').

Detailed error reporting

import { parseEnv, envvar, EnvaseError } from 'envase';
import { z } from 'zod';

try {
  parseEnv(process.env, {
    apiKey: envvar('API_KEY', z.string().min(32)),
    db: {
      host: envvar('DB_HOST', z.string().min(1)),
    },
  });
} catch (error: unknown) {
  if (EnvaseError.isInstance(error)) {
    error.message
    // Environment variables validation has failed:
    //   [API_KEY]:
    //     String must contain at least 32 character(s)
    //     (received: "short")
    //
    //   [DB_HOST]:
    //     Required
    //     (received: "undefined")

    error.issues
    //  [
    //    {
    //      "name": "API_KEY",
    //      "value": "short",
    //      "messages": ["String must contain at least 32 character(s)"]
    //    },
    //    {
    //      "name": "DB_HOST",
    //      "value": undefined,
    //      "messages": ["Required"]
    //    }
    //  ]
  }
}

Empty Values

An empty envvar (e.g. PORT=) is passed to the schema as an empty string, not as undefined. This means .default() and .optional() don't apply to it.

Number coercion would silently turn an empty or whitespace-only string into 0 (Number('') === 0, Number(' ') === 0). To prevent that, Envase reports a validation error whenever such a blank value is coerced to 0:

parseEnv({ PORT: '' }, {
  port: envvar('PORT', z.coerce.number().default(3000)),
});
// Environment variables validation has failed:
//   [PORT]:
//     Blank value cannot be coerced to a number
//     (received: "")

To use the default, leave the envvar unset, or enable the emptyStringAsUndefined option to treat empty envvars as missing:

parseEnv({ PORT: '', DOMAIN: '' }, {
  port: envvar('PORT', z.coerce.number().default(3000)),
  domain: envvar('DOMAIN', z.string().default('localhost')),
}, { emptyStringAsUndefined: true });
// { port: 3000, domain: 'localhost' }

With this option, .default() and .optional() apply to empty envvars, and required ones fail validation. Whitespace-only values are still passed to the schema unchanged. We recommend enabling it in new projects.

Sensitive Values

Mark envvars holding secrets as sensitive to keep their values out of validation errors:

parseEnv({ API_KEY: 'short' }, {
  apiKey: envvar('API_KEY', z.string().min(32), { sensitive: true }),
});
// Environment variables validation has failed:
//   [API_KEY]:
//     Too small: expected string to have >=32 characters
//     (received: [REDACTED])

When validation of a sensitive envvar fails:

  • the received value is replaced with [REDACTED] in the error message,
  • the issue in error.issues has no value and is flagged with redacted: true,
  • any occurrence of the value in messages returned by the schema library is replaced with [REDACTED].

Missing and empty values are not redacted, as they don't reveal anything. Sensitive envvars are also marked as such in the generated documentation.

Type Inference

import { envvar, type InferEnv } from 'envase';
import { z } from 'zod';

const envSchema = {
  apiKey: envvar('API_KEY', z.string().min(32)),
  db: {
    host: envvar('DB_HOST', z.string().min(1)),
  },
};

type Config = InferEnv<typeof envSchema>;
// { apiKey: string; db: { host: string } }

Computed Values

Use createConfig to derive computed values from your parsed configuration with full type inference:

import { createConfig, envvar } from 'envase';
import { z } from 'zod';

const config = createConfig(process.env, {
  schema: {
    db: {
      host: envvar('DB_HOST', z.string()),
      port: envvar('DB_PORT', z.coerce.number()),
      name: envvar('DB_NAME', z.string()),
    },
    api: {
      key: envvar('API_KEY', z.string()),
    },
  },
  computed: {
    dbConnectionString: (raw) =>
      `postgres://${raw.db.host}:${raw.db.port}/${raw.db.name}`,
    apiKeyPrefix: (raw) => raw.api.key.slice(0, 8),
  },
});

// config.db.host -> string
// config.db.port -> number
// config.dbConnectionString -> string
// config.apiKeyPrefix -> string

The raw parameter in computed functions is fully typed based on your schema, providing autocomplete and type checking. Computed values are calculated after schema validation, so you always work with parsed values (e.g., port is a number, not a string).

Nested Computed Values

Computed values can be nested to merge with your schema structure:

import { createConfig, envvar } from 'envase';
import { z } from 'zod';

const config = createConfig(process.env, {
  schema: {
    aws: {
      accessKeyId: envvar('AWS_ACCESS_KEY_ID', z.string()),
      secretAccessKey: envvar('AWS_SECRET_ACCESS_KEY', z.string()),
    },
  },
  computed: {
    aws: {
      credentials: (raw) => ({
        accessKeyId: raw.aws.accessKeyId,
        secretAccessKey: raw.aws.secretAccessKey,
      }),
    },
  },
});

// Result type:
// {
//   aws: {
//     accessKeyId: string;
//     secretAccessKey: string;
//     credentials: { accessKeyId: string; secretAccessKey: string };
//   }
// }

You can also mix flat and nested computed values:

const config = createConfig(process.env, {
  schema: {
    db: {
      host: envvar('DB_HOST', z.string()),
      port: envvar('DB_PORT', z.coerce.number()),
    },
  },
  computed: {
    // Flat at root level
    dbUrl: (raw) => `${raw.db.host}:${raw.db.port}`,
    // Nested under existing schema key
    db: {
      connectionString: (raw) => `postgres://${raw.db.host}:${raw.db.port}`,
    },
  },
});

// config.dbUrl -> string
// config.db.host -> string
// config.db.port -> number
// config.db.connectionString -> string

CLI

Automatically generate and validate markdown documentation from your environment variable schemas.

Quick Start

1. Create your schema file with a default export:

// config.ts
import { envvar, parseEnv } from 'envase';
import { z } from 'zod';

const envSchema = {
  app: {
    listen: {
      port: envvar('PORT', z.coerce.number().int().min(1024).max(65535)
        .describe('Application listening port')),
      host: envvar('HOST', z.string().default('0.0.0.0')
        .describe('Bind host address')),
    },
  },
  database: {
    url: envvar('DATABASE_URL', z.string().url()
      .describe('PostgreSQL connection URL')),
  },
};

export const config = parseEnv(process.env, envSchema);

export default envSchema

2. Generate documentation:

envase generate ./config.ts -o ./docs/env.md

3. Validate documentation (optional):

# Verify the documentation matches your schema
envase validate ./config.ts ./docs/env.md

Command Reference

envase generate <schemaPath>

Generates markdown documentation from an environment schema.

Arguments:

  • <schemaPath> - Path to a file containing default export of env schema

Options:

  • -o, --output <file> - Output file path (default: ./env-docs.md)

Usage:

envase generate ./config.ts -o ./docs/env.md

# Or use tsx for TypeScript files (recommended for older Node versions)
tsx node_modules/.bin/envase generate ./config.ts -o ./docs/env.md

# Or compile first, then generate
tsc config.ts && envase generate ./config.js -o ./docs/env.md

Generated output:

The CLI generates readable markdown documentation with:

  • Type information for each environment variable
  • Required/optional status
  • Default values
  • Descriptions (from .describe() calls)
  • Constraints (min, max, minLength, maxLength, pattern, format, etc.)
  • Enum values (for enum types)
  • Grouped by nested configuration structure
Sample generated markdown 
# Environment variables

## App / Listen

- `PORT` (optional)
  Type: `number`
  Description: Application listening port
  Min value: `1024`
  Max value: `65535`

- `HOST` (optional)
  Type: `string`
  Description: Bind host address
  Default: `0.0.0.0`

## Database

- `DATABASE_URL` (required)
  Type: `string`
  Description: PostgreSQL connection URL
  Format: `uri`

envase validate <schemaPath> <markdownPath>

Validates if a markdown file matches the documentation that would be generated from the environment schema.

Arguments:

  • <schemaPath> - Path to a file containing default export of env schema
  • <markdownPath> - Path to the markdown file to validate

Example:

envase validate ./config.ts ./docs/env.md

This command is useful for:

  • CI/CD pipelines to ensure documentation stays in sync with code
  • Pre-commit hooks to verify documentation changes
  • Detecting manual edits to generated documentation

Exit codes:

  • 0 - Validation passed (markdown matches schema)
  • 1 - Validation failed (differences found) or error occurred

API Reference

envvar

envvar(name: string, schema: StandardSchemaV1<T>, options?: EnvvarOptions)

Wraps a variable name and its schema for validation. This helps pair the raw env name with the shape you expect it to conform to.

  • options.sensitive - Redacts the received value from validation errors (see Sensitive Values)

parseEnv

parseEnv(env: Record<string, string | undefined>, envSchema: T, options?: ParseEnvOptions)

Validates envvars against the schema and returns a typed configuration object.

  • options.emptyStringAsUndefined - Treats empty envvars as missing (see Empty Values)

createConfig

createConfig(env, options)

Validates envvars and optionally computes derived values. Returns a merged object containing both the parsed config and computed values. All types are inferred from the schema and computed functions.

  • env - Environment variables object (e.g., process.env)
  • options.schema - Environment variable schema (same format as parseEnv)
  • options.computed - Optional object where each key is a function receiving the parsed config and returning a derived value
  • options.emptyStringAsUndefined - Same as in parseEnv

detectNodeEnv

detectNodeEnv(env: Record<string, string | undefined>)

Standalone utility that reads NODE_ENV and returns an object with the following boolean flags:

  • isProduction: true if NODE_ENV === 'production'
  • isTest: true if NODE_ENV === 'test'
  • isDevelopment: true if NODE_ENV === 'development'

EnvaseError

Thrown when validation fails.

Contains:

  • message: Human-readable error summary
  • issues: Array of validation issues with:
    • name: Environment variable name
    • value: Invalid value received (omitted for redacted values)
    • redacted: true if the value was omitted because the envvar is sensitive
    • messages: Validation error messages

Why Envase?

  • ✅ Works with any schema lib that follows the Standard Schema spec
  • 🔄 Supports deeply nested configs
  • 🔍 Offers rich error reporting with detailed issue breakdowns

Contributing

Contributions are welcome! If you’d like to improve this package, feel free to open an issue or submit a pull request. 🚀

If your change should be released, run pnpm changeset and commit the generated changeset file along with your code.

About

Type-safe environment variable validation with Standard Schema compliance

Resources

Readme
MIT license

Code of conduct

Code of conduct
Activity

Stars

1 star

Watchers

2 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages