babel-plugin-dotenv-import

Load environment variables using import statements.

CI

Installation

$ npm install babel-plugin-dotenv-import

Usage

.babelrc

{
  "plugins": [
    ["dotenv-import", {
      "moduleName": "@env",
      "path": ".env",
      "blocklist": null,
      "allowlist": null,
      "safe": false,
      "allowUndefined": false
    }]
  ]
}

.env

API_URL=https://api.example.org
API_TOKEN=

In users.js

import {API_URL, API_TOKEN} from "@env"

fetch(`${API_URL}/users`, {
  headers: {
    'Authorization': `Bearer ${API_TOKEN}`
  }
})

Allow and block lists

It is possible to limit the scope of env variables that will be imported by specifying a allowlist and/or a blocklist as an array of strings.

{
  "plugins": [
    ["dotenv-import", {
      "blocklist": [
        "GITHUB_TOKEN"
      ]
    }]
  ]
}

{
  "plugins": [
    ["dotenv-import", {
      "allowlist": [
        "API_URL",
        "API_TOKEN"
      ]
    }]
  ]
}

Safe mode

Enable safe mode to only allow environment variables defined in the .env file. This will completely ignore everything that is already defined in the environment.

The .env file has to exist.

{
  "plugins": [
    ["dotenv-import", {
      "safe": true
    }]
  ]
}

Allow undefined

Allow importing undefined variables, their value will be undefined.

{
  "plugins": [
    ["dotenv-import", {
      "allowUndefined": true
    }]
  ]
}

import {UNDEFINED_VAR} from '@env'

console.log(UNDEFINED_VAR === undefined) // true

When false (default behavior), an error will be thrown.

Alternatively, allowUndefined can be an array specifying the names of variables that are allowed to be undefined. Only the listed variables will be imported without errors if they are not defined, while others will still cause an error.

{
  "plugins": [
    ["dotenv-import", {
      "allowUndefined": ["ALLOWED_UNDEFINED_VAR"]
    }]
  ]
}

import {ALLOWED_UNDEFINED_VAR, UNALLOWED_UNDEFINED} from '@env'

console.log(ALLOWED_UNDEFINED_VAR === undefined) // true
console.log(UNALLOWED_UNDEFINED) // Throws an error if not defined in .env

Caveats

When using with babel-loader with caching enabled you will run into issues where environment changes won’t be picked up. This is due to the fact that babel-loader computes a cacheIdentifier that does not take your environment into account.

You can easily clear the cache:

rm -rf node_modules/.cache/babel-loader/*

Or you can override the default cacheIdentifier to include some of your environment variables.

Credits

Based on David Chang’s works on babel-plugin-dotenv.

Miscellaneous

    ╚⊙ ⊙╝
  ╚═(███)═╝
 ╚═(███)═╝
╚═(███)═╝
 ╚═(███)═╝
  ╚═(███)═╝
   ╚═(███)═╝