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.

.env.schema

# @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

@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), and also may affect other dynamic behaviour in your schema, such as the forEnv() function.

This will usually be something like APP_ENV.

• This decorator should only be set in your .env.schema 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.

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

@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

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
PUBLIC_BAR= # sensitive (explicit decorator overrides prefix)
# @sensitive=false
OTHER_BAR=  # not sensitive (explicit)

@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.

May also be used with forEnv() to disable a file based on the current env flag.

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

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

@import()

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

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 @import 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

@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)
# ---

@redactLogs

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

Options:

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

# @redactLogs=false
# ---

# @sensitive
SECRET_KEY=my-secret-value

console.log(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

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

Options:

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

# @preventLeaks=false
# ---

# @sensitive
SECRET_KEY=my-secret-value

a sample leak detection warning in an Astro project