Encrypt and Load Your .env File Securely at Runtime

Go from a plaintext .env to a securely encrypted .env.enc committed to git then decrypt it automatically at runtime using encryptd’s config() function.

This guide walks you through encrypting your first .env file and loading the decrypted variables into a Node.js application at runtime. By the end you will have a workflow where only .env.enc lives in your repository and your secrets never touch version control in plaintext.

Never commit your passphrase or your original .env file to version control. The passphrase is the only thing protecting your encrypted file treat it like a password. Store it in a secret manager and make sure .env is listed in your .gitignore.

1. Install encryptd

   If you have not installed encryptd yet, follow the Installation guide to configure GitHub Packages and add the package to your project. Then come back here.

2. Set your passphrase

   Export your passphrase as an environment variable in your current shell session. Use a long, random string this is the secret that protects your encrypted file.

   export ENV_PASSPHRASE="your-strong-passphrase"
   

   encryptd reads ENV_PASSPHRASE automatically in both the CLI and the library, so you do not need to hardcode it anywhere in your application code.

   In CI/CD environments such as GitHub Actions, store the passphrase as an encrypted repository secret and inject it as an environment variable in your workflow. Add ENV_PASSPHRASE: ${{ secrets.ENV_PASSPHRASE }} to your workflow’s env block. This keeps the value out of your source code and out of your build logs.

3. Encrypt your .env file

   Run the encrypt command from your project root. By default, encryptd reads .env and writes the encrypted output to .env.enc:

   ENV_PASSPHRASE="your-strong-passphrase" npx secure-env encrypt
   

   To encrypt a different file or write to a custom output path, pass the source and destination paths explicitly:

   ENV_PASSPHRASE="your-strong-passphrase" npx secure-env encrypt .env.production .env.production.enc
   

   After the command succeeds, you will find a .env.enc file in your project root containing a JSON blob with the encrypted salt, IV, ciphertext, and authentication tag.

4. Commit .env.enc and update .gitignore

   Add .env.enc to version control and make sure the original .env is excluded:

   # Add the encrypted file to version control
   git add .env.enc
   
   # Ensure the plaintext file is ignored
   echo ".env" >> .gitignore
   git add .gitignore
   

   Your teammates and your CI pipeline can now decrypt .env.enc using the shared passphrase without the plaintext file ever entering the repository.

5. Load encrypted variables in your application

   Call config() early in your application’s entry point, before any code that reads from process.env. It decrypts .env.enc, parses the key-value pairs, and writes them into process.env.

   import { config } from '@vernonthedev/encryptd';
   
   // Decrypts .env.enc using ENV_PASSPHRASE and populates process.env
   const env = config();
   
   console.log(env.DATABASE_URL);
   

   config() also accepts an options object when you need to customise the behaviour:

   import { config } from '@vernonthedev/encryptd';
   
   const env = config({
     path: '.env.production.enc',   // custom encrypted file path
     passphrase: 'your-passphrase', // inline passphrase (prefer ENV_PASSPHRASE)
     override: true,                // overwrite keys already set in process.env
   });
   

   config() returns a Record<string, string> containing every decrypted variable, so you can use the return value directly instead of reading from process.env if you prefer.

Decrypt from the CLI

You can also decrypt an encrypted file back to plaintext using the decrypt subcommand. This is useful for inspecting the file, rotating secrets, or applying it to an environment that cannot run Node.js code.

ENV_PASSPHRASE="your-strong-passphrase" npx secure-env decrypt .env.enc

The command decrypts the file and prints the plaintext key-value pairs to standard output. The syntax is:

secure-env decrypt [inputFile]

If inputFile is omitted, secure-env decrypt reads from .env.enc in the current directory.

Low-level library API

For advanced use cases such as encrypting or decrypting strings programmatically without touching the filesystem encryptd exports encryptEnv and decryptEnv directly.

encryptEnv(plainText, passphrase)

Encrypts a plaintext string and returns an EnvPayload object containing all fields needed to decrypt it later.

import { encryptEnv } from '@vernonthedev/encryptd';

const payload = encryptEnv('DATABASE_URL=postgres://localhost/mydb\nAPI_KEY=secret', 'your-strong-passphrase');

// payload satisfies EnvPayload:
// {
//   version?: number;
//   salt: string;   // base64-encoded random salt (used in key derivation)
//   iv: string;     // base64-encoded 96-bit nonce
//   content: string; // base64-encoded ciphertext
//   tag: string;    // base64-encoded GCM authentication tag
// }
console.log(payload);

decryptEnv(payload, passphrase)

Decrypts an EnvPayload produced by encryptEnv and returns the original plaintext string.

import { encryptEnv, decryptEnv } from '@vernonthedev/encryptd';

const payload = encryptEnv('API_KEY=mysecret', 'your-strong-passphrase');
const plaintext = decryptEnv(payload, 'your-strong-passphrase');

console.log(plaintext); // 'API_KEY=mysecret'

Type reference

interface EnvPayload {
  version?: number;
  salt: string;     // base64-encoded random salt
  iv: string;       // base64-encoded 96-bit nonce
  content: string;  // base64-encoded ciphertext
  tag: string;      // base64-encoded GCM authentication tag
}

interface ConfigOptions {
  path?: string;       // path to the encrypted file (default: '.env.enc')
  passphrase?: string; // inline passphrase (default: process.env.ENV_PASSPHRASE)
  override?: boolean;  // if true, overwrite keys already set in process.env
}