8-bit-env

8 Bit Env helps you easily manage, securely store and expose all of the environment variables and sensitive keys you need for your app. It also let's you store all your environment data next to your code in version control.

Installation

# with npm
npm i -D 8-bit-env

# or with yarn
yarn add -D 8-bit-env

Usage

8 Bit Env has an interactive command line tool which is the easiest way to use it:

npx 8-bit-env

Initializing 8 Bit Env

When you run the init script you'll first be asked to provide a master key. The master key is what 8 Bit Env uses to encrypt all of your environment data, it's essentially a password.

Once you enter your master key, 8 Bit Env will create a folder at the root directory of your project called .8bitenv and put the master key inside in a file called master.key. This file will then be added to your .gitignore file along with an entry for any environment files.

You'll then be asked to enter the names of the environments you want to store environment data for. In the example above, we're creating two, development and staging.

A *.env file will be created for each environment and stored inside the .8bitenv folder.

Adding & Saving Environment Variables

Inside the *.env files you created in the last step, you can place any environment variables or pieces of info you need to keep track of. Once it's all in there, run the save command.

When you save the files, they will be encrypted using the key inside master.key and stored as *.enc files in the .enc/ folder. The original *.env files will then be deleted (better not to have these lying around).

These encrypted files can be safely checked into version control.

Updating Environment Variables

When it's time to update your environment variables, simply run the update function which will decrypt all of the encrypted environment files using the key inside master.key, and output them as *.env files in the .8bitenv folder.

When decrypting these files, it's important the the key inside master.key is the same as when you encrypted them.

Once you have the *.env files, you can make any changes you need to make and then run the save function again.

Exposing Environment Variables

Eventually, you'll want to use these environment variables when you run your code, and depending on the environment you're running in, you'll want to use different ones.

Running expose will allow you to export the variables for a specific environment into a file of your choosing.

A common situation where this will come in handy is when using dotenv. Dotenv expects a file called .env at the root directory of your project, which it will load environment variables from. You can, for example, use expose to place all your development variables in a .env file, which dotenv will pick up on.

Creating new Environments

If you want to add a new environment, simply run the create command, which will create a *.env file for you in the .8bitenv folder.

Running from the command line

The usage section above demonstrates how to use 8 Bit Env with the interactive terminal app, but it can also be run with simple command line commands.

npx 8-bit-env init <master_key> [envName1,envName2,envName3]
npx 8-bit-env save
npx 8-bit-env update
npx 8-bit-env expose <envNameToExpose> <targetFile>
npx 8-bit-env create <envName1,envName2,envName3>

Depending on the state of your environment files, you may not be able to perform all of these. For example, if you don't have any encrypted environment files, you can't expose or update.

Running in Code

8 Bit Env exports functions for init, save, update, expose and create.

import { init, save, update, expose, create } from '8-bit-env'

// initialize 8 bit env
init()

// save any *.env files
save()

// decrypt all encrypted environment files
update()

// export a particular environments variables to a file
expose('environmentName', 'path/to/export')

// create new environment files
create(['envName1', 'envName2'])

Managing the Master Key

Anytime your code is pulled down from version control, you'll have to add in the master key again. It's important that the master key is consistant, whetever key you used when you saved the environment files, is the one you need to decrypt them.

Easily add the master key back in by running the init command, or simply adding a file called master.key to .8bitenv

If you want to change the master key, simply run the update command to decrypt all your environment files, then change the key and run save.