Node.js bindings for dotenvage - Dotenv with age encryption
npm install @dotenvage/node

Node.js bindings for
dotenvage - **Dotenv with
age encryption**.
- 🔒 Encrypt secrets in .env files - Safely commit encrypted
secrets to version control
- 📦 Native performance - Built with NAPI-RS for fast Rust
performance
- 🔄 Auto-detection - Automatically identifies which keys should
be encrypted
- 🌳 File layering - Multiple .env* files with automatic
precedence
- 💻 CLI support - Includes dotenvage command-line tool
- 📝 TypeScript support - Full TypeScript definitions included
``bash`
npm install @dotenvage/node
`typescript
import * as dotenvage from "@dotenvage/node";
// Load encrypted .env files into process.env
const loader = dotenvage.JsEnvLoaderNew();
loader.load(); // Mutates process.env (like dotenv.config())
// Now access variables
const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;
`
`typescript
import * as dotenvage from "@dotenvage/node";
const loader = dotenvage.JsEnvLoaderNew();
const env = loader.getAllVariables(); // Returns Record
// Use without modifying process.env
console.log(env.API_KEY);
console.log(env.DATABASE_URL);
`
`typescript
import * as dotenvage from "@dotenvage/node";
// Generate a new key pair
const manager = dotenvage.JsSecretManagerGenerate();
const publicKey = manager.publicKeyString(); // Share this public key
// Encrypt a secret
const secret = "sk_live_abc123";
const encrypted = manager.encryptValue(secret);
// Returns: "ENC[AGE:b64:...]"
// Decrypt it back
const decrypted = manager.decryptValue(encrypted);
console.log(decrypted === secret); // true
`
Loads and decrypts .env files.
#### JsEnvLoaderNew(): JsEnvLoader
Creates a new loader with a default SecretManager.
`typescript`
const loader = dotenvage.JsEnvLoaderNew();
#### load(): void
Loads .env files from the current directory into process.env.
`typescript`
loader.load(); // Sets variables in process.env
#### loadFromDir(dir: string): void
Loads .env files from a specific directory.
`typescript`
loader.loadFromDir("./config");
#### getAllVariableNames(): string[]
Gets all variable names from all loaded .env files (without loading
into environment).
`typescript`
const names = loader.getAllVariableNames();
console.log(names); // ["API_KEY", "DATABASE_URL", ...]
#### getAllVariables(): Record
Gets all environment variables as an object (decrypted). Note: This
loads variables into the process environment first.
`typescript`
const env = loader.getAllVariables();
console.log(env.API_KEY);
#### resolveEnvPaths(dir: string): string[]
Computes the ordered list of env file paths that would be loaded.
`typescript`
const paths = loader.resolveEnvPaths(".");
console.log(paths); // [".env", ".env.local", ...]
Manages encryption and decryption of secrets.
#### JsSecretManagerGenerate(): JsSecretManager
Generates a new random encryption key pair.
`typescript`
const manager = dotenvage.JsSecretManagerGenerate();
#### JsSecretManagerNew(): JsSecretManager
Creates a SecretManager by loading the key from standard locations:
1. DOTENVAGE_AGE_KEY environment variableAGE_KEY
2. environment variableEKG_AGE_KEY
3. environment variable~/.local/state/dotenvage/dotenvage.key
4. Key file at
`typescript`
const manager = dotenvage.JsSecretManagerNew();
#### publicKeyString(): string
Gets the public key as a string (starts with age1).
`typescript`
const publicKey = manager.publicKeyString();
#### encryptValue(plaintext: string): string
Encrypts a plaintext value.
`typescript`
const encrypted = manager.encryptValue("secret");
#### decryptValue(value: string): string
Decrypts a value if it's encrypted; otherwise returns it unchanged.
`typescript`
const decrypted = manager.decryptValue(encrypted);
#### isEncrypted(value: string): boolean
Checks if a value is in a recognized encrypted format.
`typescript`
const isEncrypted = manager.isEncrypted("ENC[AGE:b64:...]");
#### shouldEncrypt(key: string): boolean
Checks if a key name should be encrypted based on auto-detection
patterns.
`typescript`
dotenvage.shouldEncrypt("API_KEY"); // true
dotenvage.shouldEncrypt("PORT"); // false
The package includes a dotenvage CLI command:
`bash`
npx dotenvage list
npx dotenvage get API_KEY
npx dotenvage dump --export
See the
main dotenvage README
for full CLI documentation.
For Next.js applications, use the dedicated integration utilities:
`typescript`
// In next.config.mjs
import { loadEnv } from "@dotenvage/node/nextjs";
loadEnv();
Or use the pre-initialization loader to ensure environment variables
are available for Edge Runtime (middleware):
`json`
{
"scripts": {
"dev": "node -r @dotenvage/node/nextjs/preinit node_modules/.bin/next dev"
}
}
See nextjs/README.md for complete Next.js
integration documentation.
See the examples/ directory for TypeScript examples:
- load-env.ts - Loading environment variablesencrypt-decrypt.ts
- - Encryption and decryptionapp-config.ts
- - Type-safe application configurationauto-encrypt.ts
- - Auto-detection patternsnextjs-config.ts
- - Basic Next.js usage example
dotenvage supports automatic file layering with precedence:
1. .env - Base configuration.env.
2. - Environment-specific (e.g., .env.production).env.
3. - OS-specific (e.g., .env.production.linux).env.
4. - Architecture-specific.env.
5. - User-specific overrides.env.
6. - Variant-specific.env.production.linux.amd64.alice.docker
(e.g., )
Files are loaded in specificity order - more specific files override
less specific ones. Dimension values can also be discovered from
loaded files (e.g., NODE_ENV=production in .env causes.env.production to load).
Set one of these environment variables:
`bash`
export DOTENVAGE_AGE_KEY="AGE-SECRET-KEY-1..."
export AGE_KEY="AGE-SECRET-KEY-1..."
export EKG_AGE_KEY="AGE-SECRET-KEY-1..."
`typescriptPublic key: ${publicKey}
const manager = dotenvage.JsSecretManagerGenerate();
const publicKey = manager.publicKeyString();
console.log();Set: export DOTENVAGE_AGE_KEY="
console.log();`
Or use the CLI:
`bash`
npx dotenvage keygen
| Feature | dotenv | @dotenvage/node |
| -------------------- | ------ | --------------- |
| Load .env files | ✅ | ✅ |process.env
| Mutate | ✅ | ✅ |
| Encrypt secrets | ❌ | ✅ |
| Commit to git safely | ❌ | ✅ |
| File layering | ❌ | ✅ |
| Auto-detection | ❌ | ✅ |
| Native performance | ❌ | ✅ (Rust) |
- Node.js >= 18.0.0
- Valid age encryption key (set via environment variable or key file)
From the npm/ directory:
`bash`
cd npm
npm install
npm run build
Or from the project root:
`bash``
npm run npm:install
npm run npm:build
MIT - See
LICENSE
- GitHub Repository
- Rust Crate
- Rust Documentation
- Main README