vnv

A decorator enhanced .env syntax for validating your environment variables.

# linux / windows
npm install @iedan/vnv

or

# linux / windows/ mac
cargo install vnv

Examples

Validate a list of phone numbers:

@matches("[0-9]{3}-[0-9]{3}-[0-9]{4}")
CALL_LIST=["333-333-3333", "111-111-1111"]

Use a different API for development or production:

@dev
@min(9)
API_URL="http://localhost:7301"

@dev
@min(10)
@startsWith("https://")
@doesNotMatch("localhost")
API_URL="https://my-domain.dev"

Getting Started

1. Download the source code and compile the binary.

2. Set your system path variable to point to the binary.

3. Check you have it correctly configured with vnv --version

4. Download the VS Code extension for syntax highlighting here.

5. Run vnv init to setup the config file and optional template files.

6. Run vnv check to validate your environment variables

7. Run vnv build to build your .vnv file into a .env file

Variable Types

Currently valid-env supports 4 different types of environment variables.

• String
• Number
• String[]
• Number[]

For simplicity to the end user all numbers are 64 bit floating point integers.

Decorator Enhanced

valid-env extends the .env syntax with decorators that allow you to validate and scope your environment variables.

Decorators

• @public
• @private
• @dev
• @prod
• @min
• @max
• @startsWith
• @endsWith
• @matches
• @doesNotMatch

@public

Changes the scope of the environment variable to public;

Usage:

@public
PORT=3000

Allowed Variable Types

• String
• Number
• String[]
• Number[]

@private

This is not necessary as all variables by default are private but may be useful to annotate the importance for a variables privacy.

Usage:

@private
SECRET="this is a super private secret"

Allowed Variable Types

• String
• Number
• String[]
• Number[]

@dev

Changes the environment of the environment variable to dev;

Usage:

@dev
PORT=3000

Allowed Variable Types

• String
• Number
• String[]
• Number[]

@prod

Changes the environment of the environment variable to prod;

Usage:

@prod
PORT=3000

Allowed Variable Types

• String
• Number
• String[]
• Number[]

@min

Allows you to validate the minimum length or size of a variable. For number types it will validate the size of the number. For string types it will validate the length.

Usage:

@min(1000)
POLLING_INTERVAL=5000
@min(10)
DOMAIN="https://google.com"
@min(1024)
MICROSERVICE_PORTS=[8080, 8081, 8082]
@min(5)
ADMIN_EMAILS=["[email protected]", "[email protected]"]

Allowed Variable Types

• String
• Number
• String[]
• Number[]

@max

Allows you to validate the maximum length or size of a variable. For number types it will validate the size of the number. For string types it will validate the length.

Usage:

@max(45000)
POLLING_INTERVAL=5000
@max(25)
APP_NAME="super-powered-app"
@max(49151)
MICROSERVICE_PORTS=[8080, 8081, 8082]
@max(254)
ADMIN_EMAILS=["[email protected]", "[email protected]"]

Allowed Variable Types

• String
• Number
• String[]
• Number[]

@startsWith

Allows you to validate the start of a string variable.

Usage:

@startsWith("https://")
DOMAIN="https://google.com"
@startsWith("https://")
ALLOWED_ORIGINS=["https://google.com", "https://github.com"]

Allowed Variable Types

• String
• String[]

@endsWith

Allows you to validate the end of a string variable.

Usage:

@endsWith("@gmail.com")
EMAIL="[email protected]"
@endsWith("@gmail.com")
ALLOWED_ORIGINS=["[email protected]", "[email protected]"]

Allowed Variable Types

• String
• String[]

@matches

Enables regex based pattern matching to validate string variables. Will return an error when the pattern doesn't match.

Usage:

# Digits only regex
@matches("^\d+$")
PHONE_NUMBER="4427211223"
@matches("^\d+$")
PHONE_NUMBERS=["4427211223", "4427511227", "4428211213"]

Allowed Variable Types

• String
• String[]

@doesNotMatch

Enables regex based pattern matching to validate string variables. Will return an error when the pattern matches.

Usage:

# Special characters regex
@doesNotMatch("[^\w.]")
SUPER_USER="admin"
@doesNotMatch("[^\w.]")
ADMIN_USERNAMES=["johnothy", "jimnothy"]

Allowed Variable Types

• String
• String[]

Public and Private

Some environment variable handlers allow you to scope your variables to be public or private. (For example SvelteKit). This allows you to separate privileges to use environment variables between server and client code. By default all variables are scoped as private but can be marked public using the @public decorator.

Note: While the @private decorator is valid syntax and listed as a decorator it does not change the scope of the variable. However it can be useful for annotating something that should be treated as sensitive and should not be changed to public.

Environments

Sometimes you want to use different values for your variables for different environments or even different variables entirely. This is made possible with the @dev and @prod decorators.

Here are a few examples:

Different Value for same variable

@dev
PORT=3000
@prod
PORT=8080

Omit a variable from prod

@dev
KEY="..."

Omit a variable from dev

@prod
KEY="..."

Keep in mind any keys not marked with @prod or @dev will be included in all environments.

How to specify the environment

Pass the --prod or --dev flag to the check/build command. By default the environment is set to dev so theres no need to supply the --dev flag.

.vnv file:

@dev
PORT=3000
@prod
PORT=8080

Output:

C:\Users\aidan\project> vnv build --dev
Checking '.vnv'...
PORT ✔️
PORT ⏭️
Completed in 1.24ms
Completed build wrote output to .env.

Generated .env file:

# This file was generated from '.vnv' by vnv.

# @dev
PORT=3000