Skip to content
varlock

Root @decorators

Root decorators appear in the header section of a .env file - which is a comment block at the beginning of the file that ends with a divider. Usually root decorators are used only in your .env.schema file.

@envFlag

Section titled “@envFlag”

Sets the key of your environment flag, which will be used when determining if environment-specific .env files will be loaded (e.g. .env.production). This will usually be something like APP_ENV.

This will override the --env CLI flag if it is set.

⚠️ NOTE: We do not recommend using NODE_ENV as your environment flag, as it has other implications, and is often set out of your control.

See environments guide for more info

# @envFlag=APP_ENV
# ---
# @type=enum(development, staging, production)
APP_ENV=development

@defaultRequired

Section titled “@defaultRequired”

Sets the default behavior of each item being required. Can be overridden on individual items using @required or @optional.

Options:

  • true (default): All items are required unless marked optional.
  • false: All items are optional unless marked required.
  • infer: Items with a value set in .env.schema will be required; items with an empty string or no value are optional. Can be overridden per item.
# @defaultRequired=infer
# ---


FOO=bar        # required (static value)
BAR=fnCall()   # required (function value)
BAZ=           # optional (no value)
QUX=''         # optional (empty string)


# @optional
OPTIONAL_ITEM= # optional (explicit)


# @required
REQUIRED_ITEM= # required (explicit)

@defaultSensitive

Section titled “@defaultSensitive”

Sets the default state of each item being treated as sensitive. Can be overridden on individual items using @sensitive.

Options:

  • true (default): All items are sensitive unless marked otherwise.
  • false: All items are not sensitive unless marked otherwise.
  • inferFromPrefix(PREFIX): Items whose key starts with the given PREFIX are not sensitive; all others are sensitive. Useful for marking e.g. PUBLIC_ keys as non-sensitive by default.
# @defaultSensitive=inferFromPrefix(PUBLIC_)
# ---


PUBLIC_FOO= # not sensitive (due to matching prefix)
OTHER_FOO=  # sensitive (default when prefix does not match)


# @sensitive=true
PUBLIC_BAR= # sensitive (explicit decorator overrides prefix)
# @sensitive=false
OTHER_BAR=  # not sensitive (explicit)

@disable

Section titled “@disable”

Skips loading config items from a file or data source. If true, the file is ignored and no items are loaded from it. Useful for conditionally disabling a schema or env file.

# @disable  # (shorthand for @disable=true)
# ---


FOO=bar  # will be ignored
BAR=baz  # will be ignored

@generateTypes

Section titled “@generateTypes”

Enables automatic type generation based on your schema.

Key-value args:

  • lang: Language to generate types for. Supported languages:
    • ts - TypeScript
  • path: Relative filepath to output generated type file
# @generateTypes(lang=ts, path=./env.d.ts)
# ---