Root @decorators

Root decorators appear in the header section of a .env file - which is any comment block(s) at the beginning of the file, before the first config item. Usually root decorators are used only in your .env.schema file.

.env.schema

# This is the header, it can contain root decorators
# @defaultSensitive=false @defaultRequired=infer
# @generateTypes(lang=ts, path=./env.d.ts)

More details of the minutiae of decorator handling can be found in the @env-spec reference.

Built-in root decorators

These are the root decorators that are built into Varlock. Plugins may introduce more.

@currentEnv

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

@envFlag (deprecated)

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

@defaultRequired

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)

@defaultSensitive

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)

@disable

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

@import()

Arg types: [ path: string, ...keys?: string[] ]
Named args: enabled?: boolean, allowMissing?: boolean

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.

The optional enabled parameter allows conditional imports based on boolean expressions. It defaults to true if not specified.

The optional allowMissing parameter makes the import optional - if set to true, the import will be silently skipped if the file or directory doesn’t exist instead of causing a loading error. It defaults to false if not specified.

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
# @import(~/.env.shared)                          # import from home directory
# @import(./.env.dev, enabled=eq($ENV, "dev"))    # conditional import
# @import(./.env.local, allowMissing=true)        # optional import (no error if missing)
# ---

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

@setValuesBulk()

Arg types: [ data: string ] Named args: format?: "json" | "env", createMissing?: boolean, enabled?: boolean

Injects multiple config values at once from an external data source. The first argument is a resolver that produces a string (e.g., exec() calling a secrets manager), which is parsed and injected as definitions within the file containing the decorator.

Bulk values participate in the normal file override chain — process.env still overrides everything, higher-precedence files (.env.local, .env.production, etc.) override bulk values, and bulk values override schema-defined defaults in the same file. You control precedence by choosing which file to put @setValuesBulk in.

Options:

• format: How to parse the data string. json expects a flat JSON object, env expects .env file format. If not specified, auto-detected by checking if the string starts with {.
• createMissing: If true, keys in the bulk data that don’t already exist in your schema will be created as new config items. Defaults to false (unknown keys are silently skipped).
• enabled: If false, the bulk data resolver is skipped entirely. Accepts any boolean expression, including dynamic references to other config items. Defaults to true.

Can be called multiple times — later calls overwrite earlier ones for the same keys.

.env.schema

# Inject secrets from a vault as JSON
# @setValuesBulk(exec("vault kv get -format=json secret/myapp"), format=json)
# ---
API_KEY=
DB_PASSWORD=

.env.schema

# Inject from a secrets file as .env format
# @setValuesBulk(exec("cat /run/secrets/env"), format=env)
# ---
API_KEY=
DB_PASSWORD=

.env.schema

# Create items not already in the schema
# @setValuesBulk(exec("vault kv get -format=json secret/myapp"), format=json, createMissing=true)

.env.schema

# Only fetch from the vault in non-production environments
# @setValuesBulk(exec("vault kv get -format=json secret/dev"), format=json, enabled=eq($APP_ENV, "dev"))
# ---
API_KEY=
APP_ENV=dev

Note

When using format=env, function calls like $VAR references in unquoted values are not supported and will cause an error. Use single quotes for literal $ signs (e.g., '$LITERAL') or use format=json instead.

createMissing and type generation

Items created via createMissing=true — those that don’t already exist in your schema — will not be included in generated TypeScript types. Type generation happens at build/schema-load time before values are fetched, so dynamically created keys are invisible to the type generator.

For this reason, createMissing=true is not recommended. Instead, declare all expected items explicitly in your schema (with an empty value) so they are known at type-generation time.

@plugin()

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

@generateTypes()

Arg types (key/value):

• lang: Language to generate types for (currently only ts / TypeScript is supported, with more languages planned)
• path: Relative filepath to output generated type file
• auto: Controls whether types are generated automatically on every load (defaults to true). Set to false to disable automatic generation and instead run varlock typegen explicitly.
• executeWhenImported: overrides the default behaviour of not executing when the containing file is imported (defaults to false)

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

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

Tip

Usually this decorator will live in your primary .env.schema file, and it will be ignored if it is within an imported file.

To override this behaviour, set executeWhenImported to true.

Disabling automatic type generation

If you prefer to generate types manually rather than on every load, set auto=false and run varlock typegen explicitly:

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

This is useful when you want full control over when your type definitions are updated, for example in a CI pipeline or as a dedicated build step.

@redactLogs

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

Caution

There is a potential performance impact for both @preventLeaks and @redactLogs when enabled. It depends on the integration and how your application is served. Please reach out if you have any questions.

We feel that they are beneficial enough to have them on by default but you can always opt out if you prefer.

@preventLeaks

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

Caution

See note on @redactLogs about potential performance impact.