@type Data Types

The @type item decorator sets the data type associated with an item. The data type affects coercion, validation, and generated type files.

Additional data type options

All types (except enum) can be used without any arguments, but most take optional arguments that further narrow the type’s behavior.

# @type=string
NO_ARGS=
# @type=string(minLength=5, maxLength=10, toUpperCase=true)
WITH_ARGS=

Coercion & Validation Process

Once a raw value is resolved - which could from a static value in an .env file, a function, or an override passed into the process - the raw value will be coerced and validated based on the type, respecting additional arguments provided to the type.

Consider the following example:

# @type=number(precision=0, max=100)
ITEM="123.45"

The internal coercion/validation process would look like — "123.45" -> 123.45 -> 123 -> ❌ invalid (greater than max)

Default Behavior

When no @type is specified and the schema contains a static value, a type will be inferred. Otherwise, the item type will default to string.

INFERRED_STRING="foo"
INFERRED_NUMBER=123
INFERRED_BOOLEAN=true
DEFAULTS_TO_STRING_FN=someFn()
DEFAULTS_TO_STRING=

Built-in Data types

These are the built-in data types. In the future, plugins will be able to register additional data types.

string

Options:

• minLength (number): Minimum length of the string
• maxLength (number): Maximum length of the string
• isLength (number): Exact length required
• startsWith (string): Required starting substring
• endsWith (string): Required ending substring
• matches (string|RegExp): Regular expression pattern to match
• toUpperCase (boolean): Convert to uppercase
• toLowerCase (boolean): Convert to lowercase
• allowEmpty (boolean): Allow empty string (default: false)

# @type=string(minLength=5, maxLength=10, toUpperCase=true)
MY_STRING=value

number

Options:

• min (number): Minimum allowed value (inclusive)
• max (number): Maximum allowed value (inclusive)
• coerceToMinMaxRange (boolean): Coerce value to be within min/max range
• isDivisibleBy (number): Value must be divisible by this number
• isInt (boolean): Value must be an integer (equivalent to precision=0)
• precision (number): Number of decimal places to keep

# @type=number(min=0, max=100, precision=1)
MY_NUMBER=42.5

boolean

The following values will be coerced to a boolean and considered valid:

• True values: "t", "true", true, "yes", "on", "1", 1
• False values: "f", "false", false, "no", "off", "0", 0

Anything else will be considered invalid.

# @type=boolean
MY_BOOL=true

url

Options:

• prependHttps (boolean): Automatically prepend “https://” if no protocol is specified

# @type=url(prependHttps=true)
MY_URL=example.com/foobar

enum

Checks a value is contained in a list of possible values - it must match one exactly.

NOTE - this is the only type that cannot be used without any additional arguments

# @type=enum(development, staging, production)
ENV=development

email

Options:

• normalize (boolean): Convert email to lowercase

# @type=email(normalize=true)
MY_EMAIL=User@Example.com

port

Checks for valid port number. Coerces to a number.

Options:

• min (number): Minimum port number (default: 0)
• max (number): Maximum port number (default: 65535)

# @type=port(min=1024, max=9999)
MY_PORT=3000

ip

Checks for a valid IP address.

Options:

• version (4|6): IPv4 or IPv6
• normalize (boolean): Convert to lowercase

# @type=ip(version=4, normalize=true)
MY_IP=192.168.1.1

semver

Checks for a valid semantic version.

# @type=semver
MY_VERSION=1.2.3-beta.1

isoDate

Checks for valid ISO 8601 date strings with optional time and milliseconds.

# @type=isoDate
MY_DATE=2024-03-20T15:30:00Z

uuid

Checks for valid UUID (versions 1-5 per RFC4122, including NIL).

# @type=uuid
MY_UUID=123e4567-e89b-12d3-a456-426614174000

md5

Checks for valid MD5 hash.

# @type=md5
MY_HASH=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

simple-object

Validates and coerces JSON strings into objects.

# @type=simple-object
MY_OBJECT={"key": "value"}