Decorators

@Envapt binds a class property to an environment variable. It's the class-based counterpart to the Envapter readers: the same parsing, converters, and cache, declared as typed fields instead of method calls.

class Config {
    @Envapt('PORT', { converter: Converters.Number, fallback: 3000 })
    declare static readonly port: number;

    @Envapt('DEBUG', { converter: Converters.Boolean, fallback: false })
    declare static readonly debug: boolean;
}

Config.port;
       
Config.port: number

The value is read and converted once, on first access, then cached.

Declare the property, never initialize it

Always declare a decorated property with declare and no initializer.

@Envapt installs a getter on the class with Object.defineProperty. Under useDefineForClassFields (on by default for modern targets), a real field declaration emits an assignment in the constructor that overwrites that getter with undefined. The declare keyword makes the property type-only, so it emits nothing and the getter survives.

You also need experimentalDecorators enabled.

{
    "compilerOptions": {
        "experimentalDecorators": true
    }
}

Runtime-specific decorator notes (Bun running a .ts entry directly, Deno's flag) live on Compatibility.

Converters

The converter option takes the same values as getUsing/getWith: a built-in token, a primitive constructor, a custom function, or Converters.array(...). A fallback removes undefined from the value and must match the converter's type.

class Config {
    // duration token: a time-string fallback is coerced to milliseconds
    @Envapt('CACHE_TTL', { converter: Converters.Time, fallback: '15m' })
    declare static readonly cacheTtl: number;

    // array token
    @Envapt('ALLOWED_ORIGINS', { converter: Converters.array({ of: Converters.String }), fallback: [] })
    declare static readonly origins: string[];

    // custom function: receives the raw value (string, or undefined when unset)
    @Envapt('FEATURE_FLAGS', { converter: (raw) => (raw ? raw.split(',') : []) })
    declare static readonly flags: string[];
}

With no converter and no fallback, the property resolves to the raw string or null.

Shorthand decorators

@EnvNum, @EnvStr, @EnvBool, @EnvUrl, and @EnvTime are shorthands for @Envapt with a fixed converter. The call site is the key and an optional fallback.

class Config {
    @EnvNum('PORT', 3000)
    declare static readonly port: number;

    @EnvStr('AWS_REGION', 'us-east-1')
    declare static readonly region: string;

    @EnvBool('DEBUG', false)
    declare static readonly debug: boolean;

    @EnvUrl('APP_URL', new URL('http://localhost:3000'))
    declare static readonly url: URL;

    @EnvTime('CACHE_TTL', '15m')
    declare static readonly cacheTtl: number;
}

The second argument is the fallback, typed to the converter: @EnvUrl takes a URL, @EnvTime takes a millisecond number or a time string, the rest take their primitive. Omit it and the property resolves to the converted value or null. The key can also be an ordered list.

These install the same getter as @Envapt, so the declare rule applies. They take a fallback only: for required, a schema, an array, or a custom function, use @Envapt with the options object.

Required values

Pass required: true to throw EnvaptError on a missing or empty value instead of returning a fallback. It's mutually exclusive with fallback.

class Config {
    @Envapt('DATABASE_URL', { converter: Converters.Url, required: true })
    declare static readonly databaseUrl: URL;
}

The throw happens on first access to the property, independent of global strict mode. See Strict mode for the global switch and how required relates to it.

Validation with a schema

Pass a schema to validate through zod, valibot, arktype, or a hand-rolled StandardSchemaV1. The property type is the schema's output.

class Config {
    @Envapt('PORT', { schema: z.coerce.number().int().min(1024).max(65535) })
    declare static readonly port: number;
}

schema and converter are mutually exclusive. See Standard Schema for the full behavior.

Ordered keys

Like the functional readers, the key can be an ordered list. The first key with a value wins.

class Config {
    // CANARY_URL if set, otherwise APP_URL
    @Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
    declare static readonly url: URL | null;
}

Static and instance properties

@Envapt works on both static and instance properties, and the class does not need to extend anything. The cache is keyed per ClassName.property, so a static and an instance property of the same name never collide.

Extend Envapter when you also want the reader methods on the same class:

class Config extends Envapter {
    @Envapt('PORT', { converter: Converters.Number, fallback: 3000 })
    declare readonly port: number;

    // mix decorator fields with reader calls
    readonly region = this.get('AWS_REGION', 'us-east-1');
}

const config = new Config();
config.port;
       
Config.port: number

A misconfigured options object throws EnvaptError as the decorator is applied, before any property access: required together with a fallback, or a non-StandardSchemaV1 value passed as schema. See Errors for the codes.