Root @decorators

Value type: ref() (usually written as $ITEM_NAME)

Sets the current environment value, which will be used when determining if environment-specific .env files will be loaded (e.g. .env.production), and also may affect other dynamic behaviour in your schema, such as the forEnv() function. We refer to the name of this item as your environment flag.

• It must be set to a simple reference to a single config item (e.g. $APP_ENV).
• This decorator should only be set in your .env.schema file.
• The referenced item must be defined within the same file.
• This will override the --env CLI flag if it is set.
• 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.

# @currentEnv=$APP_ENV
# ---
# @type=enum(dev, preview, prod, test)
APP_ENV=dev

Value type: string (must be a valid item name within same file)

Sets the current environment flag by name.

⚠️ Deprecated at v0.1 - use @currentEnv instead.

@envFlag=APP_ENV -> @currentEnv=$APP_ENV

Value type: boolean | "infer"

Sets the default behavior of each item being required. Only applied to items that have a definition within the same file. Can be overridden on individual items using @required/@optional.

• infer (default): Items with a value set in the same file will be required; items with an empty string or no value are optional.
• true: All items are required unless marked optional.
• false: All items are optional unless marked required.

# @defaultRequired=infer
# ---

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

# @optional
OPTIONAL_ITEM=foo # optional (explicit)

# @required
REQUIRED_ITEM= # required (explicit)

Value type: boolean | inferFromPrefix(PREFIX)

Sets the default state of each item being treated as sensitive. Only applied to items that have a definition within the same file. Can be overridden on individual items using @sensitive.

• true (default): All items are sensitive unless marked otherwise.
• false: All items are not sensitive unless marked otherwise.
• inferFromPrefix(PREFIX): Item is marked not sensitive if key starts with the given PREFIX; 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
PUBLIC_BAR= # sensitive (explicit decorator overrides prefix)
# @sensitive=false
OTHER_BAR=  # not sensitive (explicit)

Value type: boolean

If true, disables loading the file - meaning no items or plugins are loaded from it. Useful for temporarily or conditionally disabling a .env file.

💡 The forEnv() function can disable an explicitly imported file based on the current environment.

# @disable  # (shorthand for @disable=true)
#
# @plugin(@varlock/x-plugin)  # will not be loaded
# ---
FOO=bar  # will be ignored

Arg types: [ path: string, ...keys?: string[] ]

Imports other .env file(s) - useful for sharing config across monorepos and splitting up large schemas. Can be called multiple times.

You may import a specific file, or a directory of files - automatically loading all .env.* files appropriately according to the current environment flag.

See the imports guide for more details and advanced usage.

# @import(./.env.imported)           # import a specific file
# @import(./.env.other, KEY1, KEY2)  # import specific keys
# @import(../shared-env/)            # import a directory
# ---

# this definition is merged with any found in imports, but this one has more precedence
IMPORTED_ITEM=overriden-value

Arg types: [ identifier: string ]

Loads a plugin, which can register new root decorators, item decorators, and resolver functions. Can be called multiple times.

See plugins guide for more details.

# @plugin(@varlock/1password-plugin)
# @initOp(allowAppAuth=true) # new root decorator
# ---
# @type=opServiceAccountToken # new data type
OP_TOKEN=
# @sensitive
XYZ_API_KEY=op(op://api-prod/xyz/api-key) # new resolver

Arg types (key/value):

• lang: Language to generate types for. Supported languages:
  • ts - TypeScript
• path: Relative filepath to output generated type file

Enables automatic type generation based on your schema. Can be called multiple times.

# @generateTypes(lang=ts, path=./env.d.ts)
# ---

Value type: boolean

Controls whether sensitive config values are automatically redacted from console output. When enabled, any sensitive values will be replaced with ▒▒▒▒▒ in logs.

Only applies in JavaScript based projects where varlock runtime code is imported.

• true (default): Console logs are automatically redacted
• false: Console logs are not redacted (useful for debugging)

# @redactLogs=false
# ---
SECRET_KEY=my-secret-value # @sensitive

console.log(process.env.SECRET_KEY)
// This will log "my▒▒▒▒▒" instead of "my-secret-value" when @redactLogs=true

Value type: boolean

Controls whether leak prevention is enabled. When enabled, varlock will scan outgoing HTTP responses to detect if sensitive values are being leaked.

Only applies in JavaScript based projects where varlock runtime code is imported.

Options:

• true (default): Leak detection is enabled
• false: Leak detection is disabled (useful for debugging)

# @preventLeaks=false
# ---
SECRET_KEY=my-secret-value # @sensitive

a sample leak detection warning in an Astro project