The EnvSchema type defines the structure of environment variable schemas used with the validateEnv function.
Type definition
type EnvSchema = Record<string, EnvSchemaValue<any>>;
EnvSchemaValue<T> is an internal type that accepts either a type constructor (String, Number, Boolean) or an EnvSchemaItem<T> object.
Description
An EnvSchema is a record (object) where:
- Keys are environment variable names (strings)
- Values can be either:
- A type constructor (
String, Number, or Boolean) for simple required variables
- An
EnvSchemaItem<T> object for advanced configuration with defaults and optional fields
Supported type constructors
The schema supports three JavaScript type constructors:
For string values. Environment variables defined with this type will be validated as strings and typed as string in TypeScript.
For numeric values. Environment variables will be converted from strings to numbers and validated that the result is not NaN. Typed as number in TypeScript.
For boolean values. Only accepts the string values 'true' or 'false' (case-sensitive). Typed as boolean in TypeScript.
Examples
Simple schema with type constructors
import { validateEnv } from 'env-core';
import type { EnvSchema } from 'env-core';
const schema: EnvSchema = {
PORT: Number,
NODE_ENV: String,
DEBUG: Boolean,
};
const env = validateEnv(schema);
// env.PORT is number
// env.NODE_ENV is string
// env.DEBUG is boolean
Schema with mixed definitions
import type { EnvSchema } from 'env-core';
const schema: EnvSchema = {
// Simple required variables
PORT: Number,
NODE_ENV: String,
// Variables with defaults
DEBUG: { type: Boolean, default: false },
HOST: { type: String, default: '0.0.0.0' },
// Optional variables
API_KEY: { type: String, required: false },
};
Creating reusable schema interfaces
import type { EnvSchema } from 'env-core';
interface DatabaseEnvSchema extends EnvSchema {
DB_HOST: typeof String;
DB_PORT: typeof Number;
DB_NAME: typeof String;
DB_SSL: {
type: typeof Boolean;
default: boolean;
};
}
const dbSchema: DatabaseEnvSchema = {
DB_HOST: String,
DB_PORT: Number,
DB_NAME: String,
DB_SSL: { type: Boolean, default: false },
};
Type inference
When you use validateEnv with a schema, TypeScript automatically infers the correct types for each property:
const schema = {
PORT: Number, // inferred as number
NODE_ENV: String, // inferred as string
DEBUG: { type: Boolean, default: false }, // inferred as boolean
} satisfies EnvSchema;
const env = validateEnv(schema);
// env has type:
// {
// PORT: number;
// NODE_ENV: string;
// DEBUG: boolean;
// }
Advanced patterns
Schema composition
Combine multiple schemas using object spread:
import type { EnvSchema } from 'env-core';
const baseSchema = {
NODE_ENV: String,
PORT: Number,
} satisfies EnvSchema;
const dbSchema = {
DB_HOST: String,
DB_PORT: Number,
} satisfies EnvSchema;
const fullSchema = {
...baseSchema,
...dbSchema,
} satisfies EnvSchema;
const env = validateEnv(fullSchema);
// env has all properties from both schemas
Conditional schema types
Create schemas that vary based on environment:
import type { EnvSchema, ValidatedEnv } from 'env-core';
type CreateSchema<T extends 'development' | 'production'> = T extends 'development'
? {
NODE_ENV: typeof String;
DEBUG: { type: typeof Boolean; default: boolean };
}
: {
NODE_ENV: typeof String;
API_KEY: typeof String;
};
const devSchema = {
NODE_ENV: String,
DEBUG: { type: Boolean, default: true },
} satisfies CreateSchema<'development'>;
Exporting typed schemas
Export your schema and its type for reuse across your application:
// envSchema.ts
import type { EnvSchema, ValidatedEnv } from 'env-core';
export const envSchema = {
PORT: Number,
NODE_ENV: String,
DEBUG: { type: Boolean, default: false },
} as const satisfies EnvSchema;
// Export the inferred type
export type Env = ValidatedEnv<typeof envSchema>;
// app.ts
import { validateEnv } from 'env-core';
import { envSchema, type Env } from './envSchema';
const env = validateEnv(envSchema);
// Use the Env type in other functions
function startServer(config: Env) {
console.log(`Starting server on port ${config.PORT}`);
}
startServer(env);
See also