dotenv-conversion




dotenv-conversion adds variable conversion on top of
dotenv. If you find yourself
needing to convert/transform environment variables to anything more useful than strings,
then
dotenv-conversion is your tool.
---
-
Installation
-
Usage
-
Preload
-
With dotenv
-
With dotenv-flow
-
Features
-
Auto-Conversion
-
Conversion Methods
-
Built-in Methods
-
Custom Methods
-
Method Aliases
-
The special built-in method auto
-
Custom Conversion for a Specific Variable
-
Prevent Variables from Conversion
-
Ignore process.env
-
Documentation
-
convert
-
Options
---
Installation
``
bash
npm install dotenv-conversion --save
`
Usage
- Standalone:
`
javascript
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenvConversion from 'dotenv-conversion'
const options = {
parsed: {
DEBUG: 'false',
},
// rememeber to set this option to false if usage is standalone
fromDotEnv: false,
}
const {parsed} = dotenvConversion.convert(options)
console.log(parsed.DEBUG) // (boolean) false
console.log(process.env.DEBUG) // (string) 'false'
`
- Integrate with dotenv
:
`
dotenv
.env file
DEBUG=false
`
`
javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.DEBUG) // (boolean) false
console.log(process.env.DEBUG) // (string) 'false'
`
- ... and dotenv-expand
:
`
dotenv
.env file
DEBUG_LEVEL=0
DEBUG=boolean:$DEBUG_LEVEL
EXPONENTIAL=2
NUMBER=1e$EXPONENTIAL
`
`
javascript
const dotenv = require('dotenv')
const dotenvExpand = require('dotenv-expand')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvExpand from 'dotenv-expand'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(dotenvExpand.expand(config))
console.log(parsed.DEBUG_LEVEL) // (number) 0
console.log(parsed.DEBUG) // (boolean) false
console.log(parsed.EXPONENTIAL) // (number) 2
console.log(parsed.NUMBER) // (number) 100
console.log(process.env.DEBUG_LEVEL) // (string) '0'
console.log(process.env.DEBUG) // (string) 'false'
console.log(process.env.EXPONENTIAL) // (string) '2'
console.log(process.env.NUMBER) // (string) '100'
`
- Or integrate with dotenv-flow
:
`
dotenv
.env.test file
DEBUG_LEVEL=0
DEBUG=boolean:$DEBUG_LEVEL
EXPONENTIAL=2
NUMBER=1e$EXPONENTIAL
`
`
javascript
const dotenvFlow = require('dotenv-flow')
const dotenvExpand = require('dotenv-expand')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenvFlow from 'dotenv-flow'
// import dotenvExpand from 'dotenv-expand'
// import dotenvConversion from 'dotenv-conversion'
// load variables from .env.test file
process.env.NODE_ENV = 'test'
const config = dotenvFlow.config()
const {parsed} = dotenvConversion.convert(dotenvExpand.expand(config))
console.log(parsed.DEBUG_LEVEL) // (number) 0
console.log(parsed.DEBUG) // (boolean) false
console.log(parsed.EXPONENTIAL) // (number) 2
console.log(parsed.NUMBER) // (number) 100
console.log(process.env.DEBUG_LEVEL) // (string) '0'
console.log(process.env.DEBUG) // (string) 'false'
console.log(process.env.EXPONENTIAL) // (string) '2'
console.log(process.env.NUMBER) // (string) '100'
`
Preload
$3
You can use the --require
(-r
) command line option
to preload dotenv
and dotenv-conversion
(and even dotenv-expand
).
By doing this, you do not need to require and load dotenv
or dotenv-conversion
(or dotenv-expand
) in your application code.
This is the preferred approach when using import
instead of require
.
`
bash
dotenv + dotenv-conversion
$ node -r dotenv-conversion/config your_script.js
dotenv + dotenv-expand + dotenv-conversion
$ node -r dotenv-conversion/config-expand your_script.js
`
The configuration options below are supported as command line arguments
in the format dotenv_config_
=.
`bash
dotenv + dotenv-conversion
$ node -r dotenv-conversion/config your_script.js dotenv_config_path=/custom/path/to/your/env/vars
dotenv + dotenv-expand + dotenv-conversion
$ node -r dotenv-conversion/config-expand your_script.js dotenv_config_path=/custom/path/to/your/env/vars
`
Additionally, you can use environment variables to set configuration options.
Command line arguments will precede these.
`bash
dotenv + dotenv-conversion
$ DOTENV_CONFIG_= node -r dotenv-conversion/config your_script.js
dotenv + dotenv-expand + dotenv-conversion
$ DOTENV_CONFIG_= node -r dotenv-conversion/config-expand your_script.js
`
`bash
dotenv + dotenv-conversion
$ DOTENV_CONFIG_ENCODING=latin1 node -r dotenv-conversion/config your_script.js dotenv_config_path=/custom/path/to/.env
dotenv + dotenv-expand + dotenv-conversion
$ DOTENV_CONFIG_ENCODING=latin1 node -r dotenv-conversion/config-expand your_script.js dotenv_config_path=/custom/path/to/.env
`
After preload, you can retrieve converted variables via global.dotenvConversion.parsed:
`dotenv
.env file
DEBUG_LEVEL=0
DEBUG=boolean:$DEBUG_LEVEL
EXPONENTIAL=2
NUMBER=1e$EXPONENTIAL
`
`javascript
// index.js file
const {parsed} = global.dotenvConversion
console.log(parsed.DEBUG_LEVEL) // (number) 0
console.log(parsed.DEBUG) // (boolean) false
console.log(parsed.EXPONENTIAL) // (number) 2
console.log(parsed.NUMBER) // (number) 100
console.log(process.env.DEBUG_LEVEL) // (string) '0'
console.log(process.env.DEBUG) // (string) 'false'
console.log(process.env.EXPONENTIAL) // (string) '2'
console.log(process.env.NUMBER) // (string) '100'
`
`bash
dotenv + dotenv-expand + dotenv-conversion
$ node -r dotenv-conversion/config-expand index.js
`
Console output:
`
0
false
2
100
0
false
2
100
`
$3
Alternatively, you can preload dotenv-flow and dotenv-conversion (and dotenv-expand).
`bash
dotenv-flow + dotenv-conversion
$ node -r dotenv-conversion/config-flow your_script.js
dotenv-flow + dotenv-expand + dotenv-conversion
$ node -r dotenv-conversion/config-flow-expand your_script.js
`
Remember to set the environment variable NODE_ENV before preloading when you need to
load NODE_ENV-specific .env file.
`bash
dotenv-flow + dotenv-conversion
$ NODE_ENV= node -r dotenv-conversion/config-flow your_script.js
dotenv-flow + dotenv-expand + dotenv-conversion
$ NODE_ENV= node -r dotenv-conversion/config-flow-expand your_script.js
`
`bash
dotenv-flow + dotenv-conversion
$ NODE_ENV=production node -r dotenv-conversion/config-flow your_script.js
dotenv-flow + dotenv-expand + dotenv-conversion
$ NODE_ENV=production node -r dotenv-conversion/config-flow-expand your_script.js
`
After preload, you can also retrieve converted variables via global.dotenvConversion.parsed.
Features
$3
By default, environment variables will be converted automatically based on its string value.
Currently, auto-conversion supports
null, undefined, boolean, number, bigint, symbol, array, object as follows:
- null
Values to be converted to null: null, Null, NULL.
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1=null
VARIABLE_2=" null "
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (object) null
console.log(parsed.VARIABLE_2) // (object) null
console.log(process.env.VARIABLE_1) // (string) 'null'
console.log(process.env.VARIABLE_2) // (string) 'null'
`
- undefined
Values to be converted to undefined: undefined, UNDEFINED.
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1=undefined
VARIABLE_2=" undefined "
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (undefined) undefined
console.log(parsed.VARIABLE_2) // (undefined) undefined
console.log(process.env.VARIABLE_1) // (string) 'undefined'
console.log(process.env.VARIABLE_2) // (string) 'undefined'
`
- boolean
Values to be converted to true: true, True, TRUE, yes, Yes, YES,
ok, Ok, OK.
Values to be converted to false: false, False, FALSE, no, No, NO,
not, Not, NOT, none, None, NONE.
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1=true
VARIABLE_2=false
VARIABLE_3=" yes "
VARIABLE_4=" no "
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (boolean) true
console.log(parsed.VARIABLE_2) // (boolean) false
console.log(parsed.VARIABLE_3) // (boolean) true
console.log(parsed.VARIABLE_4) // (boolean) false
console.log(process.env.VARIABLE_1) // (string) 'true'
console.log(process.env.VARIABLE_2) // (string) 'false'
console.log(process.env.VARIABLE_3) // (string) 'true'
console.log(process.env.VARIABLE_4) // (string) 'false'
`
- number
Values to be converted to number: NaN, ±Infinity
and any string in valid number format (e.g. ±5, ±5., ±.5, ±4.5, ±4.5e±123, ...).
Binary (e.g. ±0b1010), octal (e.g. ±0o12) and hexadecimal (e.g. ±0xa) number format
are also supported.
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1=NaN
VARIABLE_2=Infinity
VARIABLE_3=-Infinity
VARIABLE_4=5
VARIABLE_5=5.
VARIABLE_6=.5
VARIABLE_7=4.5
VARIABLE_8=4.5e+1
VARIABLE_9=4.5e+123
VARIABLE_10=-5
VARIABLE_11=-5.
VARIABLE_12=-.5
VARIABLE_13=-4.5
VARIABLE_14=-4.5e-1
VARIABLE_15=-4.5e-123
VARIABLE_16=4.5E123
VARIABLE_17=" NaN "
VARIABLE_18=" Infinity "
VARIABLE_19=" 4.5e+123 "
VARIABLE_20=0b1010
VARIABLE_21=-0B1010
VARIABLE_22=0o12
VARIABLE_23=-0O12
VARIABLE_24=0xa
VARIABLE_25=-0XA
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (number) NaN
console.log(parsed.VARIABLE_2) // (number) Infinity
console.log(parsed.VARIABLE_3) // (number) -Infinity
console.log(parsed.VARIABLE_4) // (number) 5
console.log(parsed.VARIABLE_5) // (number) 5
console.log(parsed.VARIABLE_6) // (number) 0.5
console.log(parsed.VARIABLE_7) // (number) 4.5
console.log(parsed.VARIABLE_8) // (number) 45
console.log(parsed.VARIABLE_9) // (number) 4.5e+123
console.log(parsed.VARIABLE_10) // (number) -5
console.log(parsed.VARIABLE_11) // (number) -5
console.log(parsed.VARIABLE_12) // (number) -0.5
console.log(parsed.VARIABLE_13) // (number) -4.5
console.log(parsed.VARIABLE_14) // (number) -0.45
console.log(parsed.VARIABLE_15) // (number) -4.5e-123
console.log(parsed.VARIABLE_16) // (number) 4.5e+123
console.log(parsed.VARIABLE_17) // (number) NaN
console.log(parsed.VARIABLE_18) // (number) Infinity
console.log(parsed.VARIABLE_19) // (number) 4.5e+123
console.log(parsed.VARIABLE_20) // (number) 10
console.log(parsed.VARIABLE_21) // (number) -10
console.log(parsed.VARIABLE_22) // (number) 10
console.log(parsed.VARIABLE_23) // (number) -10
console.log(parsed.VARIABLE_24) // (number) 10
console.log(parsed.VARIABLE_25) // (number) -10
console.log(process.env.VARIABLE_1) // (string) 'NaN'
console.log(process.env.VARIABLE_2) // (string) 'Infinity'
console.log(process.env.VARIABLE_3) // (string) '-Infinity'
console.log(process.env.VARIABLE_4) // (string) '5'
console.log(process.env.VARIABLE_5) // (string) '5'
console.log(process.env.VARIABLE_6) // (string) '0.5'
console.log(process.env.VARIABLE_7) // (string) '4.5'
console.log(process.env.VARIABLE_8) // (string) '45'
console.log(process.env.VARIABLE_9) // (string) '4.5e+123'
console.log(process.env.VARIABLE_10) // (string) '-5'
console.log(process.env.VARIABLE_11) // (string) '-5'
console.log(process.env.VARIABLE_12) // (string) '-0.5'
console.log(process.env.VARIABLE_13) // (string) '-4.5'
console.log(process.env.VARIABLE_14) // (string) '-0.45'
console.log(process.env.VARIABLE_15) // (string) '-4.5e-123'
console.log(process.env.VARIABLE_16) // (string) '4.5e+123'
console.log(process.env.VARIABLE_17) // (string) 'NaN'
console.log(process.env.VARIABLE_18) // (string) 'Infinity'
console.log(process.env.VARIABLE_19) // (string) '4.5e+123'
console.log(process.env.VARIABLE_20) // (string) '10'
console.log(process.env.VARIABLE_21) // (string) '-10'
console.log(process.env.VARIABLE_22) // (string) '10'
console.log(process.env.VARIABLE_23) // (string) '-10'
console.log(process.env.VARIABLE_24) // (string) '10'
console.log(process.env.VARIABLE_25) // (string) '-10'
`
* Note:* You can disable the support for binary, octal or hexadecimal number format
by setting the option binaryNumber,
octalNumber or hexadecimalNumber to false.
- bigint
Values to be converted to bigint must match the format: ${value}n;
value must be an integer in decimal (e.g. ±10), binary (e.g. ±0b1010),
octal (e.g. ±0o12) or hexadecimal (e.g. ±0xa) number syntax.
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1=5n
VARIABLE_2=-5n
VARIABLE_3=" 5n "
VARIABLE_4=0b1010n
VARIABLE_5=-0B1010n
VARIABLE_6=0o12n
VARIABLE_7=-0O12n
VARIABLE_8=0xan
VARIABLE_9=-0XAn
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (bigint) 5n
console.log(parsed.VARIABLE_2) // (bigint) -5n
console.log(parsed.VARIABLE_3) // (bigint) 5n
console.log(parsed.VARIABLE_4) // (bigint) 10n
console.log(parsed.VARIABLE_5) // (bigint) 10n
console.log(parsed.VARIABLE_6) // (bigint) 10n
console.log(parsed.VARIABLE_7) // (bigint) 10n
console.log(parsed.VARIABLE_8) // (bigint) 10n
console.log(parsed.VARIABLE_9) // (bigint) 10n
console.log(process.env.VARIABLE_1) // (string) '5n'
console.log(process.env.VARIABLE_2) // (string) '-5n'
console.log(process.env.VARIABLE_3) // (string) '5n'
console.log(process.env.VARIABLE_4) // (string) '10n'
console.log(process.env.VARIABLE_5) // (string) '10n'
console.log(process.env.VARIABLE_6) // (string) '10n'
console.log(process.env.VARIABLE_7) // (string) '10n'
console.log(process.env.VARIABLE_8) // (string) '10n'
console.log(process.env.VARIABLE_9) // (string) '10n'
`
* Note:* You can disable the support for binary, octal or hexadecimal bigint format
by setting the option binaryBigInt,
octalBigInt or hexadecimalBigInt to false.
- symbol
Values to be converted to symbol must match the format: Symbol(${string}).
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1=Symbol()
VARIABLE_2=Symbol(a)
VARIABLE_3=" Symbol(a) "
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (symbol) Symbol()
console.log(parsed.VARIABLE_2) // (symbol) Symbol(a)
console.log(parsed.VARIABLE_3) // (symbol) Symbol(a)
console.log(process.env.VARIABLE_1) // (string) 'Symbol(a)'
console.log(process.env.VARIABLE_2) // (string) 'Symbol(a)'
`
- array
Values to be converted to array must match the format:
a string contains ${value} separated by commas;
the value could be null,boolean, number, "string", [..array..] or {..object..};
and all could be wrapped or not wrapped by [ and ] (must , when the string is empty).
Special case: Values that have only a string enclosed by double quotes
also match the above format.
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1=[null,true,1,"a",[-1,2.1,3e1,4.5e123],{"x":"y"}]
VARIABLE_2=null,true,1,"a",[-1,2.1,3e1,4.5e123],{"x":"y"}
VARIABLE_3=" [null, true, 1, \" x y \"] "
VARIABLE_4=" null, true, 1, \" x y \" "
VARIABLE_5=" [ ] "
VARIABLE_6="\"a\"" # Special case
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (array) [null, true, 1, "a", [-1, 2.1, 30, 4.5e+123], {"x": "y"}]
console.log(parsed.VARIABLE_2) // (array) [null, true, 1, "a", [-1, 2.1, 30, 4.5e+123], {"x": "y"}]
console.log(parsed.VARIABLE_3) // (array) [null, true, 1, " x y "]
console.log(parsed.VARIABLE_4) // (array) [null, true, 1, " x y "]
console.log(parsed.VARIABLE_5) // (array) []
console.log(parsed.VARIABLE_6) // (array) ["a"] // Special case
console.log(process.env.VARIABLE_1) // (string) '[null,true,1,"a",[-1,2.1,30,4.5e+123],{"x":"y"}]'
console.log(process.env.VARIABLE_2) // (string) '[null,true,1,"a",[-1,2.1,30,4.5e+123],{"x":"y"}]'
console.log(process.env.VARIABLE_3) // (string) '[null,true,1," x y "]'
console.log(process.env.VARIABLE_4) // (string) '[null,true,1," x y "]'
console.log(process.env.VARIABLE_5) // (string) '[]'
console.log(process.env.VARIABLE_6) // (string) '["a"]' // Special case
`
- object
Values to be converted to object must match the format:
a string contains ${key}:${value} separated by commas;
the key must be "string" and
the value could be null,boolean, number, "string", [..array..] or {..object..};
and all could be wrapped or not wrapped by { and } (must , when the string is empty).
Spaces will be trimmed.
`dotenv
.env file
VARIABLE_1={"a":null,"b":true,"c":1,"d":"x","e":[-1,2.1,3e1,4.5e123],"f":{"y":"z"}}
VARIABLE_2="\"a\":null,\"b\":true,\"c\":1,\"d\":\"x\",\"e\":[-1,2.1,3e1,4.5e123],\"f\":{\"y\":\"z\"}"
VARIABLE_3=" [\"a\": null, \"b\": true, \"c\": 1, \"d\": \" x y \"] "
VARIABLE_4=" \"a\": null, \"b\": true, \"c\": 1, \"d\": \" x y \" "
VARIABLE_5=" { } "
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (object) {"a": null, "b": true, "c": 1, "d": "x", "e": [-1, 2.1, 30, 4.5e+123], "f": {"x": "y"}}
console.log(parsed.VARIABLE_2) // (object) {"a": null, "b": true, "c": 1, "d": "x", "e": [-1, 2.1, 30, 4.5e+123], "f": {"x": "y"}}
console.log(parsed.VARIABLE_3) // (object) {"a": null, "b": true, "c": 1, "d": " x y "}
console.log(parsed.VARIABLE_4) // (object) {"a": null, "b": true, "c": 1, "d": " x y "}
console.log(parsed.VARIABLE_5) // (object) {}
console.log(process.env.VARIABLE_1) // (string) '{"a":null,"b":true,"c":1,"d":"x","e":[-1,2.1,30,4.5e+123],"f":{"y":"z"}}'
console.log(process.env.VARIABLE_2) // (string) '{"a":null,"b":true,"c":1,"d":"x","e":[-1,2.1,30,4.5e+123],"f":{"y":"z"}}'
console.log(process.env.VARIABLE_3) // (string) '{"a":null,"b":true,"c":1,"d":" x y "}'
console.log(process.env.VARIABLE_4) // (string) '{"a":null,"b":true,"c":1,"d":" x y "}'
console.log(process.env.VARIABLE_5) // (string) '{}'
`
$3
Auto-Conversion also looks for the conversion method indicated by a variable
when it cannot convert that variable to anything but a string,
and uses the method to make the conversion.
How a variable indicates its conversion method:
- Standalone:
`javascript
const options = {
parsed: {
'${VARIABLE_1}': '${method}:${value}',
'${VARIABLE_2}': ' ${method}: ${value} ',
},
fromDotEnv: false,
}
// Example:
const options = {
parsed: {
BOOLEAN: 'boolean:1',
NUMBER: ' number: true ',
},
fromDotEnv: false,
}
// Unaccepted (no conversion):
const options = {
parsed: {
NOT_BOOLEAN: 'boolean :1',
NOT_NUMBER: ' number : true ',
},
fromDotEnv: false,
}
`
- Within .env files:
`dotenv
${VARIABLE_1}=${method}:${value}
${VARIABLE_2}=" ${method}: ${value} "
Example:
BOOLEAN=boolean:1
NUMBER=" number: true "
Unaccepted (no conversion):
NOT_BOOLEAN="boolean :1"
NOT_NUMBER=" number : true "
`
* Note:* method is case-sensitive.
#### Built-in Methods
Here are built-in conversion methods (boolean, number, bigint, string, symbol, array, object)
that can be used now:
- boolean
This method is to convert any value to true or false.
`dotenv
.env file
VARIABLE_1="boolean:" #
VARIABLE_2="boolean:false" # or: false, False, FALSE
VARIABLE_3="boolean:no" # or: no, No, NO
VARIABLE_4="boolean:not" # or: not, Not, NOT
VARIABLE_5="boolean:none" # or: none, None, NONE
VARIABLE_6="boolean:null" # or: null, Null, NULL
VARIABLE_7="boolean:undefined" # or: undefined, UNDEFINED
VARIABLE_8=boolean:NaN
VARIABLE_9=boolean:0
VARIABLE_10=boolean:0.0e+0
VARIABLE_11=boolean:0n
VARIABLE_12=boolean:[]
VARIABLE_13=boolean:{}
VARIABLE_14="boolean:anything else"
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (boolean) false
console.log(parsed.VARIABLE_2) // (boolean) false
console.log(parsed.VARIABLE_3) // (boolean) false
console.log(parsed.VARIABLE_4) // (boolean) false
console.log(parsed.VARIABLE_5) // (boolean) false
console.log(parsed.VARIABLE_6) // (boolean) false
console.log(parsed.VARIABLE_7) // (boolean) false
console.log(parsed.VARIABLE_8) // (boolean) false
console.log(parsed.VARIABLE_9) // (boolean) false
console.log(parsed.VARIABLE_10) // (boolean) false
console.log(parsed.VARIABLE_11) // (boolean) false
console.log(parsed.VARIABLE_12) // (boolean) false
console.log(parsed.VARIABLE_13) // (boolean) false
console.log(parsed.VARIABLE_14) // (boolean) true
console.log(process.env.VARIABLE_1) // (string) 'false'
console.log(process.env.VARIABLE_2) // (string) 'false'
console.log(process.env.VARIABLE_3) // (string) 'false'
console.log(process.env.VARIABLE_4) // (string) 'false'
console.log(process.env.VARIABLE_5) // (string) 'false'
console.log(process.env.VARIABLE_6) // (string) 'false'
console.log(process.env.VARIABLE_7) // (string) 'false'
console.log(process.env.VARIABLE_8) // (string) 'false'
console.log(process.env.VARIABLE_9) // (string) 'false'
console.log(process.env.VARIABLE_10) // (string) 'false'
console.log(process.env.VARIABLE_11) // (string) 'false'
console.log(process.env.VARIABLE_12) // (string) 'false'
console.log(process.env.VARIABLE_13) // (string) 'false'
console.log(process.env.VARIABLE_14) // (string) 'true'
`
- number
This method is to convert any value to number.
`dotenv
.env file
VARIABLE_1="number:" #
VARIABLE_2="number:true" # or: True, TRUE
VARIABLE_3="number:yes" # or: Yes, YES
VARIABLE_4="number:ok" # or: Ok, OK
VARIABLE_5="number:false" # or: False, FALSE
VARIABLE_6="number:no" # or: No, NO
VARIABLE_7="number:not" # or: Not, NOT
VARIABLE_8="number:none" # or: None, NONE
VARIABLE_9="number:null" # or: Null, NULL
VARIABLE_10="number:undefined" # or: UNDEFINED
VARIABLE_11=number:NaN
VARIABLE_12="number:Infinity" # or: +Infinity
VARIABLE_13=number:-Infinity
VARIABLE_14=number:4.5e1
VARIABLE_15=number:-4.5e-1
VARIABLE_16=number:4.5e123
VARIABLE_17=number:123string
VARIABLE_18=number:string
VARIABLE_19=number:[]
VARIABLE_20=number:{}
VARIABLE_21=number:0b1010
VARIABLE_22=number:0b1010string
VARIABLE_23=number:0o12
VARIABLE_24=number:0o12string
VARIABLE_25=number:0xa
VARIABLE_26=number:0xastring
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (number) 0
console.log(parsed.VARIABLE_2) // (number) 1
console.log(parsed.VARIABLE_3) // (number) 1
console.log(parsed.VARIABLE_4) // (number) 1
console.log(parsed.VARIABLE_5) // (number) 0
console.log(parsed.VARIABLE_6) // (number) 0
console.log(parsed.VARIABLE_7) // (number) 0
console.log(parsed.VARIABLE_8) // (number) 0
console.log(parsed.VARIABLE_9) // (number) 0
console.log(parsed.VARIABLE_10) // (number) NaN
console.log(parsed.VARIABLE_11) // (number) NaN
console.log(parsed.VARIABLE_12) // (number) Infinity
console.log(parsed.VARIABLE_13) // (number) -Infinity
console.log(parsed.VARIABLE_14) // (number) 45
console.log(parsed.VARIABLE_15) // (number) -0.45
console.log(parsed.VARIABLE_16) // (number) 4.5e+123
console.log(parsed.VARIABLE_17) // (number) 123
console.log(parsed.VARIABLE_18) // (number) 0
console.log(parsed.VARIABLE_19) // (number) 0
console.log(parsed.VARIABLE_20) // (number) 0
console.log(parsed.VARIABLE_21) // (number) 10
console.log(parsed.VARIABLE_22) // (number) 0
console.log(parsed.VARIABLE_23) // (number) 10
console.log(parsed.VARIABLE_24) // (number) 0
console.log(parsed.VARIABLE_25) // (number) 10
console.log(parsed.VARIABLE_26) // (number) 0
console.log(process.env.VARIABLE_1) // (string) '0'
console.log(process.env.VARIABLE_2) // (string) '1'
console.log(process.env.VARIABLE_3) // (string) '1'
console.log(process.env.VARIABLE_4) // (string) '1'
console.log(process.env.VARIABLE_5) // (string) '0'
console.log(process.env.VARIABLE_6) // (string) '0'
console.log(process.env.VARIABLE_7) // (string) '0'
console.log(process.env.VARIABLE_8) // (string) '0'
console.log(process.env.VARIABLE_9) // (string) '0'
console.log(process.env.VARIABLE_10) // (string) 'NaN'
console.log(process.env.VARIABLE_11) // (string) 'NaN'
console.log(process.env.VARIABLE_12) // (string) 'Infinity'
console.log(process.env.VARIABLE_13) // (string) '-Infinity'
console.log(process.env.VARIABLE_14) // (string) '45'
console.log(process.env.VARIABLE_15) // (string) '-0.45'
console.log(process.env.VARIABLE_16) // (string) '4.5e+123'
console.log(process.env.VARIABLE_17) // (string) '123'
console.log(process.env.VARIABLE_18) // (string) '0'
console.log(process.env.VARIABLE_19) // (string) '0'
console.log(process.env.VARIABLE_20) // (string) '0'
console.log(process.env.VARIABLE_21) // (string) '10'
console.log(process.env.VARIABLE_22) // (string) '0'
console.log(process.env.VARIABLE_23) // (string) '10'
console.log(process.env.VARIABLE_24) // (string) '0'
console.log(process.env.VARIABLE_25) // (string) '10'
console.log(process.env.VARIABLE_26) // (string) '0'
`
* Note:* You can disable the conversion for binary, octal or hexadecimal number format
by setting the option binaryNumber,
octalNumber or hexadecimalNumber to false.
- bigint
This method is to convert any value to bigint.
`dotenv
.env file
VARIABLE_1="bigint:" #
VARIABLE_2="bigint:true" # or: True, TRUE
VARIABLE_3="bigint:yes" # or: Yes, YES
VARIABLE_4="bigint:ok" # or: Ok, OK
VARIABLE_5="bigint:false" # or: False, FALSE
VARIABLE_6="bigint:no" # or: No, NO
VARIABLE_7="bigint:not" # or: Not, NOT
VARIABLE_8="bigint:none" # or: None, NONE
VARIABLE_9="bigint:null" # or: Null, NULL
VARIABLE_10="bigint:undefined" # or: UNDEFINED
VARIABLE_11=bigint:NaN
VARIABLE_12="bigint:Infinity" # or: +Infinity
VARIABLE_13=bigint:-Infinity
VARIABLE_14=bigint:4
VARIABLE_15=bigint:-4.5
VARIABLE_16=bigint:4.5e1
VARIABLE_17=bigint:4.5e10
VARIABLE_18=bigint:4.5e-123
VARIABLE_19=bigint:123string
VARIABLE_20=bigint:string
VARIABLE_21=bigint:[]
VARIABLE_22=bigint:{}
VARIABLE_23=bigint:0b1010
VARIABLE_24=bigint:0b1010string
VARIABLE_25=bigint:0o12
VARIABLE_26=bigint:0o12string
VARIABLE_27=bigint:0xa
VARIABLE_28=bigint:0xastring
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (bigint) 0n
console.log(parsed.VARIABLE_2) // (bigint) 1n
console.log(parsed.VARIABLE_3) // (bigint) 1n
console.log(parsed.VARIABLE_4) // (bigint) 1n
console.log(parsed.VARIABLE_5) // (bigint) 0n
console.log(parsed.VARIABLE_6) // (bigint) 0n
console.log(parsed.VARIABLE_7) // (bigint) 0n
console.log(parsed.VARIABLE_8) // (bigint) 0n
console.log(parsed.VARIABLE_9) // (bigint) 0n
console.log(parsed.VARIABLE_10) // (bigint) 0n
console.log(parsed.VARIABLE_11) // (bigint) 0n
console.log(parsed.VARIABLE_12) // (bigint) 1n
console.log(parsed.VARIABLE_13) // (bigint) -1n
console.log(parsed.VARIABLE_14) // (bigint) 4n
console.log(parsed.VARIABLE_15) // (bigint) -4n
console.log(parsed.VARIABLE_16) // (bigint) 45n
console.log(parsed.VARIABLE_17) // (bigint) 45000000000n
console.log(parsed.VARIABLE_18) // (bigint) 0n
console.log(parsed.VARIABLE_19) // (bigint) 123n
console.log(parsed.VARIABLE_20) // (bigint) 0n
console.log(parsed.VARIABLE_21) // (bigint) 0n
console.log(parsed.VARIABLE_22) // (bigint) 0n
console.log(parsed.VARIABLE_23) // (bigint) 10n
console.log(parsed.VARIABLE_24) // (bigint) 0n
console.log(parsed.VARIABLE_25) // (bigint) 10n
console.log(parsed.VARIABLE_26) // (bigint) 0n
console.log(parsed.VARIABLE_27) // (bigint) 10n
console.log(parsed.VARIABLE_28) // (bigint) 0n
console.log(process.env.VARIABLE_1) // (string) '0n'
console.log(process.env.VARIABLE_2) // (string) '1n'
console.log(process.env.VARIABLE_3) // (string) '1n'
console.log(process.env.VARIABLE_4) // (string) '1n'
console.log(process.env.VARIABLE_5) // (string) '0n'
console.log(process.env.VARIABLE_6) // (string) '0n'
console.log(process.env.VARIABLE_7) // (string) '0n'
console.log(process.env.VARIABLE_8) // (string) '0n'
console.log(process.env.VARIABLE_9) // (string) '0n'
console.log(process.env.VARIABLE_10) // (string) '0n'
console.log(process.env.VARIABLE_11) // (string) '0n'
console.log(process.env.VARIABLE_12) // (string) '1n'
console.log(process.env.VARIABLE_13) // (string) '-1n'
console.log(process.env.VARIABLE_14) // (string) '4n'
console.log(process.env.VARIABLE_15) // (string) '-4n'
console.log(process.env.VARIABLE_16) // (string) '45n'
console.log(process.env.VARIABLE_17) // (string) '45000000000n'
console.log(process.env.VARIABLE_18) // (string) '0n'
console.log(process.env.VARIABLE_19) // (string) '123n'
console.log(process.env.VARIABLE_20) // (string) '0n'
console.log(process.env.VARIABLE_21) // (string) '0n'
console.log(process.env.VARIABLE_22) // (string) '0n'
console.log(process.env.VARIABLE_23) // (string) '10n'
console.log(process.env.VARIABLE_24) // (string) '0n'
console.log(process.env.VARIABLE_25) // (string) '10n'
console.log(process.env.VARIABLE_26) // (string) '0n'
console.log(process.env.VARIABLE_27) // (string) '10n'
console.log(process.env.VARIABLE_28) // (string) '0n'
`
* Note:* You can disable the conversion for binary, octal or hexadecimal bigint format
by setting the option binaryBigInt,
octalBigInt or hexadecimalBigInt to false.
- string
This method is to keep any value as it is.
`dotenv
.env file
VARIABLE_1=string:true
VARIABLE_2=string:4.5e1
VARIABLE_3=" string: anything "
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (string) 'true'
console.log(parsed.VARIABLE_2) // (string) '4.5e1'
console.log(parsed.VARIABLE_3) // (string) ' anything '
console.log(process.env.VARIABLE_1) // (string) 'true'
console.log(process.env.VARIABLE_2) // (string) '4.5e1'
console.log(process.env.VARIABLE_3) // (string) ' anything '
`
* Note:* Auto-Conversion will use the conversion method string for all variables
that it cannot convert to anything but a string.
So, VARIABLE=text is also the same as VARIABLE=string:text.
- symbol
This method is to convert any value to symbol.
`dotenv
.env file
VARIABLE_1="symbol:"
VARIABLE_2="symbol: "
VARIABLE_3="symbol:a"
VARIABLE_4="symbol: a "
VARIABLE_5="symbol:Symbol()"
VARIABLE_6="symbol:Symbol( )"
VARIABLE_7="symbol:Symbol(a)"
VARIABLE_8="symbol:Symbol( a )"
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (symbol) Symbol()
console.log(parsed.VARIABLE_2) // (symbol) Symbol(" ")
console.log(parsed.VARIABLE_3) // (symbol) Symbol("a")
console.log(parsed.VARIABLE_4) // (symbol) Symbol(" a ")
console.log(parsed.VARIABLE_5) // (symbol) Symbol()
console.log(parsed.VARIABLE_6) // (symbol) Symbol(" ")
console.log(parsed.VARIABLE_7) // (symbol) Symbol("a")
console.log(parsed.VARIABLE_8) // (symbol) Symbol(" a ")
console.log(process.env.VARIABLE_1) // (string) 'Symbol()'
console.log(process.env.VARIABLE_2) // (string) 'Symbol( )'
console.log(process.env.VARIABLE_3) // (string) 'Symbol(a)'
console.log(process.env.VARIABLE_4) // (string) 'Symbol( a )'
console.log(process.env.VARIABLE_5) // (string) 'Symbol()'
console.log(process.env.VARIABLE_6) // (string) 'Symbol( )'
console.log(process.env.VARIABLE_7) // (string) 'Symbol(a)'
console.log(process.env.VARIABLE_8) // (string) 'Symbol( a )'
`
- array
This method is to convert the value to array.
If the value cannot be converted, it will be returned itself.
`dotenv
.env file
VARIABLE_1="array:" #
VARIABLE_2="array: [ ] "
VARIABLE_3=array:[null,true,1,"x",[-1,2.1,3e1,4.5e123],{"y":"z"}]
VARIABLE_4=array:null,true,1,"x",[-1,2.1,3e1,4.5e123],{"y":"z"}
VARIABLE_5="array: 1, 2, 3"
VARIABLE_6="array: \"a\", \"b\", \"c\""
VARIABLE_7="array: a, b, c"
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (array) []
console.log(parsed.VARIABLE_2) // (array) []
console.log(parsed.VARIABLE_3) // (array) [null, true, 1, "x", [-1, 2.1, 30, 4.5e+123], {"y": "z"}]
console.log(parsed.VARIABLE_4) // (array) [null, true, 1, "x", [-1, 2.1, 30, 4.5e+123], {"y": "z"}]
console.log(parsed.VARIABLE_5) // (array) [1, 2, 3]
console.log(parsed.VARIABLE_6) // (array) ["a", "b", "c"]
console.log(parsed.VARIABLE_7) // (string) ' a, b, c'
console.log(process.env.VARIABLE_1) // (string) '[]'
console.log(process.env.VARIABLE_2) // (string) '[]'
console.log(process.env.VARIABLE_3) // (string) '[null,true,1,"x",[-1,2.1,30,4.5e+123],{"y":"z"}]'
console.log(process.env.VARIABLE_4) // (string) '[null,true,1,"x",[-1,2.1,30,4.5e+123],{"y":"z"}]'
console.log(process.env.VARIABLE_5) // (string) '[1,2,3]'
console.log(process.env.VARIABLE_6) // (string) '["a","b","c"]'
console.log(process.env.VARIABLE_7) // (string) ' a, b, c'
`
- object
This method is to convert any value to object.
If the value cannot be converted, it will be returned itself.
`dotenv
.env file
VARIABLE_1="object:" #
VARIABLE_2="object: { } "
VARIABLE_3=object:{"a":null,"b":true,"c":1,"d":"x","e":[-1,2.1,3e1,4.5e123],"f":{"y":"z"}}
VARIABLE_4=object:"a":null,"b":true,"c":1,"d":"x","e":[-1,2.1,3e1,4.5e123],"f":{"y":"z"}
VARIABLE_5="object: \"a\": 1, \"b\": 2, \"c\": 3"
VARIABLE_6="object: \"a\": \"x\", \"b\": \"y\", \"c\": \"z\""
VARIABLE_7="object: a: 1, b: 2, c: 3"
VARIABLE_8="object: \"a\": x, \"b\": y, \"c\": z"
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (object) {}
console.log(parsed.VARIABLE_2) // (object) {}
console.log(parsed.VARIABLE_3) // (object) {"a": null, "b": true, "c": 1, "d": "x", "e": [-1, 2.1, 30, 4.5e+123], "f": {"y": "z"}}
console.log(parsed.VARIABLE_4) // (object) {"a": null, "b": true, "c": 1, "d": "x", "e": [-1, 2.1, 30, 4.5e+123], "f": {"y": "z"}}
console.log(parsed.VARIABLE_5) // (object) {"a": 1, "b": 2, "c": 3}
console.log(parsed.VARIABLE_6) // (object) {"a": "x", "b": "y", "c": "z"}
console.log(parsed.VARIABLE_7) // (string) ' a: 1, b: 2, c: 3'
console.log(parsed.VARIABLE_7) // (string) ' "a": x, "b": y, "c": z'
console.log(process.env.VARIABLE_1) // (string) '{}'
console.log(process.env.VARIABLE_2) // (string) '{}'
console.log(process.env.VARIABLE_3) // (string) '{"a": null,"b":true,"c":1,"d":"x","e":[-1,2.1,30,4.5e+123],"f":{"y":"z"}}'
console.log(process.env.VARIABLE_4) // (string) '{"a": null,"b":true,"c":1,"d":"x","e":[-1,2.1,30,4.5e+123],"f":{"y":"z"}}'
console.log(process.env.VARIABLE_5) // (string) '{"a":1,"b":2,"c":3}'
console.log(process.env.VARIABLE_6) // (string) '{"a":"x","b":"y","c":"z"}'
console.log(process.env.VARIABLE_7) // (string) ' a: 1, b: 2, c: 3'
console.log(process.env.VARIABLE_8) // (string) ' "a": x, "b": y, "c": z'
`
#### Custom Methods
Here you can extend the dotenv-conversion by defining your own custom conversion methods.
- Add new conversion method:
`dotenv
.env file
VARIABLE_1=custom:agree
VARIABLE_2=custom:disagree
VARIABLE_3=custom2:yes
VARIABLE_4=custom2:agree
VARIABLE_5=custom2:disagree
VARIABLE_6=no_custom:yes
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// Define new conversion methods named custom and custom2
config.methods = {
// brand new method
custom(value) {
return value === 'agree' ? true : false
},
// or want to reuse methods via this
custom2(value, ...params) {
// reuse built-in method
// When reusing any conversion method,
// make sure you pass all available params of the method to it
if (this.boolean(value, ...params)) {
return true
}
// reuse custom method
return this.custom(value)
},
}
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (boolean) true
console.log(parsed.VARIABLE_2) // (boolean) false
console.log(parsed.VARIABLE_3) // (boolean) true
console.log(parsed.VARIABLE_4) // (boolean) true
console.log(parsed.VARIABLE_5) // (boolean) false
console.log(parsed.VARIABLE_6) // (string) 'no_custom:yes'
console.log(process.env.VARIABLE_1) // (string) 'true'
console.log(process.env.VARIABLE_2) // (string) 'false'
console.log(process.env.VARIABLE_3) // (string) 'true'
console.log(process.env.VARIABLE_4) // (string) 'true'
console.log(process.env.VARIABLE_5) // (string) 'false'
console.log(process.env.VARIABLE_6) // (string) 'no_custom:yes'
`
- Override built-in conversion methods:
`dotenv
.env file
VARIABLE_1=text
VARIABLE_2=string:text
VARIABLE_3=boolean:yes
VARIABLE_4=boolean:true
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// Override built-int methods string and boolean
config.methods = {
string(value) {
return value.toUpperCase()
},
boolean(value) {
return value === 'yes' ? true : false
},
}
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (string) 'TEXT'
console.log(parsed.VARIABLE_2) // (string) 'TEXT'
console.log(parsed.VARIABLE_3) // (boolean) true
console.log(parsed.VARIABLE_4) // (boolean) false
console.log(process.env.VARIABLE_1) // (string) 'TEXT'
console.log(process.env.VARIABLE_2) // (string) 'TEXT'
console.log(process.env.VARIABLE_3) // (string) 'true'
console.log(process.env.VARIABLE_4) // (string) 'false'
`
* Note:* A conversion method always has 3 params in order: value, name and config.
`dotenv
.env file
VARIABLE=text
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const dotenvConfig = dotenv.config()
// Override built-int methods string
dotenvConfig.methods = {
string(value, name, config) {
console.log('value:', value)
console.log('name:', name)
console.log('config:', config)
return value
},
}
const {parsed} = dotenvConversion.convert(dotenvConfig)
/* CONSOLE OUTPUT:
value: text
name: VARIABLE
config: {
parsed: { ... },
methods: { ... },
...
}
*/
`
#### Method Aliases
When you don't like the (long) method name, but you don't want to change it directly
as well as you don't want to define a new method with a better name (and reuse the old method),
here is the feature for you.
`dotenv
.env file
VARIABLE_1=b:yes
VARIABLE_2=uppercase:text
VARIABLE_3=U:text
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// (optional) Define new custom conversion method name uppercase
config.methods = {
uppercase(value) {
return value.toUpperCase()
},
}
// Define the method aliases
config.methodAliases = {
// Alias to the built-in method boolean
b: 'boolean',
// (optional) Alias to the brand new method uppercase
U: 'uppercase',
}
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (boolean) true
console.log(parsed.VARIABLE_2) // (string) 'TEXT'
console.log(parsed.VARIABLE_3) // (string) 'TEXT'
console.log(process.env.VARIABLE_1) // (string) 'true'
console.log(process.env.VARIABLE_2) // (string) 'TEXT'
console.log(process.env.VARIABLE_3) // (string) 'TEXT'
`
There are also built-in aliases which are ready to use:
- bool => boolean
- num => number
- big => bigint
- str => string
- arr => array
- obj => object
`dotenv
.env file
VARIABLE_1=bool:yes
VARIABLE_2=num:4.5e123
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (boolean) true
console.log(parsed.VARIABLE_2) // (number) 4.5e+123
console.log(process.env.VARIABLE_1) // (string) 'true'
console.log(process.env.VARIABLE_2) // (string) '4.5e+123'
`
* Note:*
- You cannot override existing aliases.
- Alias named by existing methods is not allowed
- Alias to other alias is not allowed.
`dotenv
.env file
VARIABLE_1=customBool:yes
VARIABLE_2=customString:text
VARIABLE_3=bool:yes
VARIABLE_4=string:text
VARIABLE_5=b:yes
VARIABLE_6=cb:yes
VARIABLE_7=cs:text
VARIABLE_8=bl:yes
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// New custom methods
config.methods = {
customBool(value) {
return CUSTOM_BOOL:${value}
},
customString(value) {
return CUSTOM_STRING:${value}
},
}
config.methodAliases = {
// Not allowed aliases:
// - Override the existing alias bool,
// expect the custom method customBool instead of the method boolean to work
bool: 'customBool',
// - Alias named by the existing method string,
// expects the custom method customString to work
string: 'customString',
// - Alias to the existing alias bool,
// expects the method boolean to work
b: 'bool',
// Fixing not allowed aliases
cb: 'customBool',
cs: 'customString',
bl: 'boolean',
}
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (string) 'CUSTOM_BOOL:yes'
console.log(parsed.VARIABLE_2) // (string) 'CUSTOM_STRING:text'
console.log(parsed.VARIABLE_3) // (boolean) true // wrong expect: 'CUSTOM_BOOL:yes'
console.log(parsed.VARIABLE_4) // (string) 'text' // wrong expect: 'CUSTOM_STRING:text'
console.log(parsed.VARIABLE_5) // (string) 'b:yes' // wrong expect: true
console.log(parsed.VARIABLE_6) // (string) 'CUSTOM_BOOL:yes'
console.log(parsed.VARIABLE_7) // (string) 'CUSTOM_STRING:text'
console.log(parsed.VARIABLE_8) // (boolean) true
console.log(process.env.VARIABLE_1) // (string) 'CUSTOM_BOOL:yes'
console.log(process.env.VARIABLE_2) // (string) 'CUSTOM_STRING:text'
console.log(process.env.VARIABLE_3) // (string) 'true'
console.log(process.env.VARIABLE_4) // (string) 'text'
console.log(process.env.VARIABLE_5) // (string) 'b:yes'
console.log(process.env.VARIABLE_6) // (string) 'CUSTOM_BOOL:yes'
console.log(process.env.VARIABLE_7) // (string) 'CUSTOM_STRING:text'
console.log(process.env.VARIABLE_8) // (string) 'true'
`
* *Only alphanumeric (a-z, A-Z, 0-9), underscore (_) and dot (.) characters are allowed in naming the conversion
methods and aliases.*
#### The special built-in method auto
The Auto-Conversion uses the built-in conversion method auto
for its automated execution.
Logically, you can override it. But certainly, it is HIGHLY NOT RECOMMENDED ,
unless you want to change the whole auto-conversion process.
`dotenv
.env file
VARIABLE_1=text
VARIABLE_2=true
VARIABLE_3=123.5
VARIABLE_4=boolean:yes
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// Override the conversion method auto
config.methods = {
auto(value) {
return 'overridden'
},
}
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (string) 'overridden'
console.log(parsed.VARIABLE_2) // (string) 'overridden'
console.log(parsed.VARIABLE_3) // (string) 'overridden'
console.log(parsed.VARIABLE_4) // (string) 'overridden'
console.log(process.env.VARIABLE_1) // (string) 'overridden'
console.log(process.env.VARIABLE_2) // (string) 'overridden'
console.log(process.env.VARIABLE_3) // (string) 'overridden'
console.log(process.env.VARIABLE_4) // (string) 'overridden'
`
* Note:* The override will affect only the Auto-Conversion feature.
Besides, you need to avoid these worthless actions:
- Defining aliases to the auto.
- Defining custom conversions that point to the auto.
- Using auto like other methods to indicate conversion:
- Standalone: {AUTO_BOOLEAN: "auto:true"}, or
- Within .env files: AUTO_BOOLEAN=auto:true.
The reuse of the method auto could be an option if you know what to do:
`dotenv
.env file
STATE=state:stop
RUNNING_VALUE=true
STOPPED_VALUE_1={"reason":"reason1"}
STOPPED_VALUE_2={"reason":"reason2","code":123}
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
const originEnv = {...config.parsed}
// Define custom method state to replace current value with the value coming from
// other environment variables which need to convert automatically.
config.methods = {
state(value, ...params) {
switch (value) {
case 'running':
value = originEnv.RUNNING_VALUE
break
case 'stop2':
value = originEnv.STOPPED_VALUE_2
break
case 'stop1':
default:
value = originEnv.STOPPED_VALUE_1
break
}
// When reusing any conversion method,
// make sure you pass all available params of the method to it
return this.auto(value, ...params)
},
}
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.STATE) // (object) {"reason": "reason1"}
console.log(process.env.STATE) // (string) '{"reason":"reason1"}'
`
$3
Custom conversion for a specific variable could be a function or
a string refers to a conversion method or alias as follows:
`dotenv
.env file
VARIABLE_1=agree
VARIABLE_2=agree
VARIABLE_3=agree
VARIABLE_4=0
VARIABLE_5=0
VARIABLE_6=0
VARIABLE_7=0
VARIABLE_8=boolean:true
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// Define custom conversion for specific variables
config.specs = {
// Custom conversion for VARIABLE_2
VARIABLE_2(value) {
return value === 'agree' ? true : false
},
// Custom conversion for VARIABLE_3
VARIABLE_3(value) {
// reuse custom conversion
return this.VARIABLE_2(value)
},
// Custom conversion for VARIABLE_5
VARIABLE_5(value, ...params) {
// reuse conversion method
// When reusing any conversion method,
// make sure you pass all available params of the method to it
return config.methods.boolean(value, ...params)
},
// Custom conversion for VARIABLE_6
VARIABLE_6: 'boolean', // use the conversion method boolean
// Custom conversion for VARIABLE_7
VARIABLE_7: 'bool', // use the conversion method alias bool -> boolean
// Custom conversion for VARIABLE_8
VARIABLE_8: 'anything-else', // the conversion method string will be used by default
}
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (string) 'agree'
console.log(parsed.VARIABLE_2) // (boolean) true
console.log(parsed.VARIABLE_3) // (boolean) true
console.log(parsed.VARIABLE_4) // (number) 0
console.log(parsed.VARIABLE_5) // (boolean) false
console.log(parsed.VARIABLE_6) // (boolean) false
console.log(parsed.VARIABLE_7) // (boolean) false
console.log(parsed.VARIABLE_8) // (string) 'boolean:true'
console.log(process.env.VARIABLE_1) // (string) 'agree'
console.log(process.env.VARIABLE_2) // (string) 'true'
console.log(process.env.VARIABLE_3) // (string) 'true'
console.log(process.env.VARIABLE_4) // (string) '0'
console.log(process.env.VARIABLE_5) // (string) 'false'
console.log(process.env.VARIABLE_6) // (string) 'false'
console.log(process.env.VARIABLE_7) // (string) 'false'
console.log(process.env.VARIABLE_8) // (string) 'boolean:true'
``
* Note:* The function used in custom conversion also has 3 params in order
like the conversion methods: value, name and config.
See the note at the end of Custom Methods .
$3
`dotenv
.env file
VARIABLE_1=boolean:true
VARIABLE_2=object:{"foo":"bar"}
VARIABLE_3=boolean:true
VARIABLE_4=object:{"foo":"bar"}
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// Declare variables that should be excluded in any conversion
config.prevents = ['VARIABLE_3', 'VARIABLE_4']
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE_1) // (boolean) true
console.log(parsed.VARIABLE_2) // (object) {"foo": "bar"}
console.log(parsed.VARIABLE_3) // (string) 'bool:true'
console.log(parsed.VARIABLE_4) // (string) 'object:{"foo":"bar"}'
console.log(process.env.VARIABLE_1) // (string) 'true'
console.log(process.env.VARIABLE_2) // (string) '{"foo":"bar"}'
console.log(process.env.VARIABLE_3) // (string) 'bool:true'
console.log(process.env.VARIABLE_4) // (string) 'object:{"foo":"bar"}'
`
$3
By default, after conversion, the variables will also be saved into process.env with their values kept in string
format.
If you want to ignore this execution, please do as follows:
- Standalone:
`javascript
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const options = {
parsed: {
VARIABLE: 'yes',
},
fromDotEnv: false,
}
// Ignore process.env
options.ignoreProcessEnv = true
const {parsed} = dotenvConversion.convert(options)
console.log(parsed.VARIABLE) // (boolean) true
console.log(process.env.VARIABLE) // (undefined) undefined // if not ignore, value will be 'true'
`
- With dotenv:
`dotenv
.env file
VARIABLE=yes
`
`javascript
const dotenv = require('dotenv')
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenv from 'dotenv'
// import dotenvConversion from 'dotenv-conversion'
const config = dotenv.config()
// Ignore process.env
config.ignoreProcessEnv = true
const {parsed} = dotenvConversion.convert(config)
console.log(parsed.VARIABLE) // (boolean) true
console.log(process.env.VARIABLE) // (string) 'yes' // if not ignore, value will be 'true'
`
Documentation
dotenv-conversion exposes only 1 function:
- convert
$3
convert function will convert environment variables inside the parsed option.
Its return value is the options used in conversion with the parsed option
now containing the converted environment variables.
`javascript
const dotenvConversion = require('dotenv-conversion')
/ or ES6 /
// import dotenvConversion from 'dotenv-conversion'
const options = {
parsed: {
// ... environment variables
},
fromDotEnv: false, // if usage is standalone
}
const result = dotenvConversion.convert(options)
console.log(result)
/* CONSOLE OUTPUT:
{
parsed: {
// ... converted environment variables
},
fromDotEnv: false,
// ... other options
}
*/
`
#### Options
##### parsed
Type: object.
This option contains environment variables before and after converting.
##### fromDotEnv
Type: boolean. Default: true.
If using with dotenv or dotenv-flow, please do not set this option,
or set it to true. Otherwise, remember to set it to false.
See usage .
This option is due to an issue of dotenv
that has not been resolved yet. When it is true, dotenv-conversion will apply its own fix.
##### ignoreProcessEnv
Type: boolean. Default: false.
If this option is set to false, the environment variables' values
after converting will be written back to process.env.
If this option is set to true, they won't.
See this feature .
##### binaryNumber
Type: boolean. Default: true.
If this option is set to false, the string in binary number format
will not be converted to number.
##### octalNumber
Type: boolean. Default: true.
If this option is set to false, the string in octal number format
will not be converted to number.
##### hexadecimalNumber
Type: boolean. Default: true.
If this option is set to false, the string in hexadecimal number format
will not be converted to number.
##### binaryBigInt
Type: boolean. Default: true.
If this option is set to false, the string in binary bigint format
will not be converted to bigint.
##### octalBigInt
Type: boolean. Default: true.
If this option is set to false, the string in octal bigint format
will not be converted to bigint.
##### hexadecimalBigInt
Type: boolean. Default: true.
If this option is set to false, the string in hexadecimal bigint format
will not be converted to bigint.
##### prevents
Type: array. Default: [].
List of environment variables which won't be converted.
See this feature .
##### specs
Type: object. Default: {}.
Contains custom conversions for specific environment variables.
See this feature .
##### methods
Type: object. Default: {}.
Contains custom conversion methods.
See this feature .
##### methodAliases
Type: object. Default: {}`.
Contains conversion method aliases.
See this feature .