@adonisjs/env

Env

Environment variables parser and reader for Node.js. This module parses the raw string in dotfile format and set process.env variables from it. Also, you can make use of bash like syntax for variable interpolation.

Table of contents

• Usage
• Usage with AdonisJs
• Casting values
• Variable interpolation
  • Following will fail
  • Do this instead
  • Escape characters
• API
• Maintainers

Usage

Install the package from npm as follows:

npm i @adonisjs/env

# yarn
yarn add @adonisjs/env

and then use it as follows

import { env } from '@adonisjs/env/build/standalone'

env.process(`
  PORT=3333
  HOST=127.0.0.1
`)

and then read the values as follows

env.get('PORT')

// or
process.env.PORT

The Env.process method will not overwrite the existing environment variables (that is how it should be). However, if you want to overwrite existing values, maybe inside testing environment, then you can call the process method as follows:

env.process('PORT=3333', true)

Usage with AdonisJs

The @adonisjs/core includes this module and hence there is no need to install it seperately. However, here are the instructions to setup the provider.

export const providers = [
  '@adonisjs/env/build/providers/EnvProvider',
]

After this, you have to register the typings file inside files array for Typescript to pick the ambient module.

All this hassle is required, since this module is never meant to be installed standalone.

tsconfig.json

{
  "files": ["./node_modules/@adonisjs/env/build/adonis-typings/env.d.ts"]
}

The EnvProvider will look for .env file is the project root and parses it's content automatically. When not using this with AdonisJs, then you need to perform this process by yourself.

Casting values

The values saved as environment variables are always string. However, this module does the values casting for you, when you read them using Env.get.

env.process(`
  CACHE_VIEWS=false
`)

process.env.CACHE_VIEWS // string
env.get('CACHE_VIEWS') // boolean

Following values are casted

.env Value	Casted value
'null'	null
'true'	true
'1'	true
'false'	false
'0'	false

Variable interpolation

You can also reference environment variables by using bash like interpolation syntax.

env.process(`
  HOST=localhost
  PORT=3333
  URL=$HOST:$PORT
`)

All letter, numbers and _ after the dollar sign will be considered as a variable reference. Any other characters apart from the above mentioned aren't allowed. However, you can wrap your variable substitution inside curly braces {} when using characters other than the whitelisted one's.

Following will fail

The following reference to $REDIS-USER will fail, since the parser will stop at - and consider USER as a static string.

env.process(`
  REDIS-USER=foo
  REDIS-URL=localhost@$REDIS-USER
`)

Do this instead

The usage of curly braces {} tells the parser to parse until the closing brace.

env.process(`
  REDIS-USER=foo
  REDIS-URL=localhost@${REDIS-USER}
`)

Escape characters

Quite often, you will have strings where you want the $ dollar character to be considered as a literal value. In that case you can escape the character as follows.

env.process(`
  PASSWORD=pa\\$\\$word
`)

process.env.PASSWORD // pa$$word

DO NOTE: The usage of double escape \\ is required when you are typing the string directly in Javascript, since the first escape is swallowed by JS. However, if you are writing the enviornment variables inside the .env file, then a single escape \ is required.

API

Following are the autogenerated files via Typedoc

• API

Maintainers

Harminder virk