According to The Twelve-Factor App, configuration should be strictly separated from code and instead defined in environment variables. If you have found this best practice to be inconvenient in your dev environment, then you may want to give purescript-dotenv
a try.
By effectively allowing a configuration file to be consumed through the purescript-node-process
environment API, this library enables your application code to leverage environment variables in production while easing the burden of setting them in development and test environments.
Simply place your .env
configuration file in the root of your project (ensuring for security reasons not to commit it), and then call Dotenv.loadFile
at the beginning of your program. Environment variable lookups throughout your program will then fall back to the values defined in .env
.
via spago:
spago install dotenv
First, place a .env
file in the root of your project directory. See the Configuration Format section for more information.
Next, import the Dotenv
module at the entry point of your program (i.e. Main.purs
):
import Dotenv (loadFile) as Dotenv
The loadFile
function runs in Aff
, so you will also need to import something like launchAff_
:
import Effect.Aff (launchAff_)
Finally, call the loadFile
function from your main
function before the rest of your program logic:
main :: Effect Unit
main = launchAff_ do
Dotenv.loadFile
liftEffect do
testVar <- lookupEnv "TEST_VAR"
logShow testVar
The .env
file may generally define one environment variable setting per line in the format VARIABLE_NAME=value
. For example:
[email protected]
EMAIL_SUBJECT=Testing
EMAIL_BODY=It worked!
Text prefixed with #
is recognized as a comment and ignored. A comment may appear on its own line or at the end of a line containing a setting. For example:
# Application Settings
GREETING=Hello, Sailor! # A friendly greeting
Setting values may be wrapped with single or double quotes. This is required when the value contains a #
character so that it is not treated as a comment. It is also necessary when the value includes line breaks. For example:
SUBJECT="This one weird trick will double your productivity"
MESSAGE="Dear friend,
Insert compelling message here.
Sincerely,
Bob"
The value of an environment variable (or another setting) can be interpolated into a setting value using the ${VARIABLE_NAME}
syntax. For example:
DB_HOST=127.0.0.1
DB_NAME=myappdb
DB_USER=dbuser
DB_CONN_STR=postgresql://${DB_USER}:${DB_PASS}@${DB_HOST}/${DB_NAME}
The standard output of a command can also be interpolated into a setting value using the $(command)
syntax. In the following example, the output of the whoami
command is interpolated into the database connection string:
DB_HOST=127.0.0.1
DB_NAME=myappdb
DB_CONN_STR=postgresql://$(whoami):${DB_PASS}@${DB_HOST}/${DB_NAME}
For a complete specification of parsing rules, please see the parser tests.
To run the examples, clone the repository and run one of the following depending on your package manager and build tool, replacing <example-name>
with the name of one of the examples.
spago run -p example/<example-name>.purs -m Example.<example-name>
- Haskell: stackbuilders/dotenv-hs
- Haskell: pbrisbin/load-env
- JavaScript: motdotla/dotenv
- Python: theskumar/python-dotenv
- Ruby: bkeepers/dotenv