About @env-spec

Overview

@env-spec is a DSL that extends normal .env syntax. It allows adding structured metadata using @decorator style comments (similar to JSDoc) and a syntax for setting values via function calls.

A short example:

# Stripe secret api key
# @required @sensitive @type=string(startsWith="sk_")
# @docsUrl=https://docs.stripe.com/keys
STRIPE_SECRET_KEY=encrypted("asdfqwerqwe2374298374lksdjflksdjf981273948okjdfksdl")

Why is this useful?

This structured data can be used by libraries to provide: additional validation, coercion, type-safety on your env vars extra guard-rails around handling @sensitive data more flexible loading logic without additional application code or config files

This schema information is most valuable when it is shared across team members and machines. So, it is intended to be committed to git. In most cases, this means creating a .env.schema containing all schema info and possibly some default values. Practically speaking, this is similar to the .env.example file used by many projects. The difference is that now the schema can be used on an ongoing basis instead of just once to create an untracked local copy.

Building on this, you could use additional files which set values. They could add additional items or override properties of existing ones. Whether you want to use a single git-ignored .env file, or apply a cascade of environment-specific files (e.g., .env, .env.local, .env.test, etc) is up to you. However the new ability to use function calls to safely decrypt data, or load values from external sources, means you’ll likely be tempted to use committed .env files much more.

An env-spec enabled tool would load all env files appropriately, merging together both schema and values, as well as additional values read from the shell/process. Then the schema would be applied which could transform and fill values, for example decrypting or fetching from an external source, as well as applying coercion and validation. Backwards compatibility

This is designed to be mostly backwards compatible with traditional .env files. However, there is no standard .env spec and various tools have different rules and features. So we made some decisions to try to standardize things. Tools may support additional compatibility flags if users want to opt in/out of specific behaviours that match other tools.

The extended feature set means an env-spec enabled parser will successfully parse env files that other tools may not.

What is included in env-spec?

This package defines a parser and related tools for parsing an @env-spec enabled .env file. It does not provide anything past this parsing step, such as actually loading environment variables.

Why did we create this?

We previously created DMNO and saw immense value in this schema-driven approach to configuration. With env-spec, we wanted to provide a standard that could benefit anyone who uses .env files (and even those who don’t!). There’s an incredible ecosystem of libraries and tools that have adopted .env, and we want to make it easier for everyone to benefit from additional guardrails, with as little upfront work as possible.

We’ve also seen the explosion of AI-assisted coding tools which means that users are even more likely to leak sensitive configuration items, like API keys. If we can help to improve the security posture for these users, then hopefully that improves things for everyone. How can I help? If you’re a maintainer, author, contributor, or an opinionated user of tools that rely on .env files, please read through our RFC. We are not trying to build in a vacuum and we want your input. We’d also love your feedback on varlock which is built on top of @env-spec since it provides (we hope!) a solid reference implementation.

If this resonates with you, please reach out. We welcome your feedback and we welcome additional contributors.

@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
# @int=123 @float=123.456 @willBeString=123.456.789
# @quoted="with spaces" @trueString="true"
# @singleQuote='hi' @backTickQuote=`hi`
# @withNewline="new\nline"`
# @funcCallNoArgs=func() @dec=funcCallArray(val1, "val2") @dec=funcCallObj(k1=v1, k2="v2")

Invalid decorator examples:

# @
# @int=
# @spaceNeedsQuotes=spaces without quotes
# @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 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 values may be wrapped in either ( " | """ | ``` )
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 the item ITEM1=foo # post comment
This post-comment can contain decorators ITEM1=foo # @required

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)