Env Stage Loader

Loads .env files in order based on process.env.NODE_ENV value.

1. shell
2. .env.{environment}.local
3. .env.{environment}
4. .env.local
5. .env

If environment variable is set, any file loaded after will not override it.

Usage

Import and use asap in your build process or app

const loadStageEnv = require('env-stage-loader')

// Load env variables
const values = loadStageEnv()
console.log('resolved values', values)

// Debug load order & value setting
loadStageEnv({ debug: true })

// Set env dynamically
loadStageEnv({
  env: 'development'
})

// Force override of any env variable
loadStageEnv({
  forceSet: {
    FOO: 'this value will win'
  }
})

// Force override of any env variable
loadStageEnv({
  env: 'development'
  // Force unsetting of all previously found ENV vars found in shell
  unloadEnv: true
})

Examples

[stage].local takes presidence

/*
.env.dev.local contains FOO=BAR
.env.dev contains FOO=ZAZ
*/

const values = loadStageEnv({ env: 'dev' })

console.log(values.FOO === process.env.FOO)
console.log(process.env.FOO)
// value "BAR" from .env.dev.local

shell takes presidence

/*
process.env.XYZ === '123'
.env.dev.local contains XYZ=345
.env.dev contains XYZ=987
*/

const values = loadStageEnv({ env: 'dev' })

console.log(process.env.XYZ)
// value "123" from original shell process

Another shell example

# Shell value set
export FOO=1

FOO is set in shell session...

/*
.env file contains FOO=ZAZ
*/

const values = loadStageEnv({ env: 'dev' })

console.log(process.env.FOO)
// process.env.FOO === "1" because shell takes precedence

Run tests for more examples.

Typical .env files used

• .env: Default.
• .env.local: Local overrides. This file is loaded for all environments except test.
• .env.development, .env.test, .env.production: Environment-specific settings.
• .env.development.local, .env.test.local, .env.production.local: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right:

• npm start: .env.development.local, .env.local, .env.development, .env

These variables will act as the defaults if the machine does not explicitly set them.

Please refer to the dotenv documentation for more details.

Alternative Packages

• dotenv-flow
• https://www.npmjs.com/package/universal-dotenv
• https://github.com/thenativeweb/nodeenv
• https://github.com/af/envalid