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, then you may want to give purescript-dotenv a try.

By 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 reducing 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.

bower:

bower install --save purescript-dotenv

psc-package:

psc-package install dotenv

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

For a complete example, see example/Main.purs and the corresponding .env file.

The .env file may generally define one environment variable setting per line in the format VARIABLE_NAME=value. Here is a trivial example:

EMAIL_FROM=noreply@my.app
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. The following example differs from the variable substitution example above by interpolating the output of the whoami command into the database connection string instead of a DB_USER setting:

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 example, clone the repository and run one of the following depending on your package manager and build tool.

bower + pulp:

bower install
pulp run -I example

spago:

spago run -p example/Main.purs

• Haskell: stackbuilders/dotenv-hs
• Haskell: pbrisbin/load-env
• JavaScript: motdotla/dotenv
• Python: theskumar/python-dotenv
• Ruby: bkeepers/dotenv