@env-spec Reference

We don’t make any assumptions about the meaning of specific decorators, or function calls. Comments

Comments in env-spec (like dotenv) start with a #. Comments can be either on their own line, or at the end of a line after something else.

# this is a comment
KEY=val # so is this
# but this is invalid

We give these comments additional meaning by letting them contain @decorators and attaching them to specific config items.

Comment A regular comment is a comment that does not start with @

Leading whitespace is optional — #these, # are, # all valid
Decorators within are ignored — # this @decorator is ignored

DecoratorComment A decorator comment is a comment that starts with an @ and contains decorators

It may contain one or multiple decorators — # @type=integer, # @sensitive @required
There may be an additional regular comment after the decorator(s) — # @sensitive=false # key is published in final build Divider A divider is a comment that serves as a separator, like a horizontal line
A comment starting with --- or === is considered a divider — # ---, # ===
A single leading whitespace is optional — # ---, #---
Anything after that is ignored and valid — # --- some info, # ------------ CommentBlock A comment block is a group of continuous comments that is not attached to a specific config item.
The comment block is ended by an empty line, a Divider, or the end of the file.
Both DecoratorComments and RegularComments may be interpersed

DocumentHeader If a CommentBlock ends with a Divider and is the first element of the document, it will be considered the Header.

Decorators from this header can be used to configure all contained elements, or the loading process itself

Decorators

A Decorator is used within comments to attach structured data to specific config items or to the entire document and loading process.

Each decorator has a name and optional value — @name=value
Using the name only is equivalent to setting the value to true — @required === @required=true
Decorator values will be parsed using the common value-handling rules (see below)

Valid decorator examples:

# @willBeTrue @willBeFalse=false @explicitTrue=true @undef=undefined @trueString="true"
# @int=123 @float=123.456 @willBeString=123.456.789
# @doubleQuoted="with spaces" @singleQuote='hi' @backTickQuote=`hi`
# @unquoted=this-works-too @withNewline="new\nline"
# @funcCallNoArgs=func() @dec=funcCallArray(val1, "val2") @dec=funcCallObj(k1=v1, k2="v2")

Invalid decorator examples:

# @
# @int=
# @noNewLines="new
#              laksdjf"

Config Items

Config items define individual env vars. Each has a key, an optional value, and optional attached comments.

Keys must start with [a-ZA-Z_], followed by any of [a-ZA-Z0-9_] — ✅ SOME_ITEM, ❌ BAD-KEY, ❌ 2BAD_KEY
Setting no value is allowed and will be treated as undefined — UNDEF_VAR=
An explicit empty string is allowed — EMPTY_STRING_VAR=""
Single-line values may be wrapped in quotes or not, and will follow the common value-handling rules (see below)
Multi-line string values may be wrapped in either ( ' | " | """ | ``` ) - but we strongly recommend using triple backticks only for consistency
Only comments directly preceeding the item will be attached to the item
However a Divider will break the above comments into a CommentBlock that is not attached to the item
An additional post-comment can appear after an item ITEM1=foo # post comment
- This post-comment may contain decorators too ITEM1=foo # @required (not recommended)

Common Value-Handling Rules

Values are interpreted similarly for config item values, decorator values, and values within function call arguments. Values may be wrapped in quotes or not, but handling varies slightly.

Values may never contain actual newlines, but may contain the string \n
Values do not have to be wrapped in quotes if they do not contain spaces
Unquoted values also may not contain other characters depending on the context:
- ConfigItem values may not contain [ #]
- Decorator values may not contain [ #]
- FunctionCall args may not contain [ ,)]
Unquoted values will coerce true, false, undefined — @foo=false
Unquoted values will coerce numeric values — @int=123 @float=123.456
Otherwise unquoted values will be treated as a string
A value in quotes is always be treated as a string — @d1="with spaces" @trueString="true", @numStr="123"
All quote styles [`'"] are ok — @dq="c" @bt=`b` @sq='a'
Escaped quotes matching the wrapping quote style are ok — @ok="escaped\"quote"
In quote-wrapped values, the string \n will be converted to an actual newline

Function calls

If a value is not wrapped in quotes and looks like a function call - for example encrypted(ASDF123...) - we will interpret it as a FunctionCall. This is relevant both for config item values and decorator values.

function names must start with a letter, and can then contain letters, numbers, and underscores /[a-ZA-Z][a-ZA-Z0-9_]*/
function args are always interpreted as either an array or object
you can pass no args, a single value, or multiple
or you may pass key value pairs, and the args will be interpreted as an object
each value will be interpreted using common value-handling rules (see above)

Examples:

# @noArgs=fn()
# @oneArg=fn(asdf) @oneArgQuoted=fn("with quotes")
# @multipleArgs=fn(one, "two", three, 123.456)
# @objArgs=fn(key1=v1, key2="v2", key3=true)