@dotenvage/node


Node.js bindings for
dotenvage - **Dotenv with
age encryption**.

Features

- 🔒 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

Installation

``bash
npm install @dotenvage/node
`

Quick Start

$3

`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;
`

$3

`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);
`

$3

`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
`

API Reference

$3

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", ...]
`

$3

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 variable
2. AGE_KEY environment variable
3. EKG_AGE_KEY environment variable
4. Key file at ~/.local/state/dotenvage/dotenvage.key

`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:...]");
`

$3

#### 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
`

CLI Usage

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.

Next.js Integration

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.

TypeScript Examples

See the examples/ directory for TypeScript examples:

- load-env.ts - Loading environment variables
- encrypt-decrypt.ts - Encryption and decryption
- app-config.ts - Type-safe application configuration
- auto-encrypt.ts - Auto-detection patterns
- nextjs-config.ts - Basic Next.js usage example

File Layering

dotenvage supports automatic file layering with precedence:

1. .env - Base configuration
2. .env. - Environment-specific (e.g., .env.production)
3. .env.. - OS-specific (e.g., .env.production.linux)
4. .env... - Architecture-specific
5. .env.... - User-specific overrides
6. .env..... - Variant-specific
(e.g., .env.production.linux.amd64.alice.docker)

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).

Key Management

$3

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..."
`

$3

`typescript
const manager = dotenvage.JsSecretManagerGenerate();
const publicKey = manager.publicKeyString();
console.log(Public key: ${publicKey});
console.log(Set: export DOTENVAGE_AGE_KEY="");
`

Or use the CLI:

`bash
npx dotenvage keygen
`

Comparison with dotenv

| Feature | dotenv | @dotenvage/node |
| -------------------- | ------ | --------------- |
| Load .env files | ✅ | ✅ |
| Mutate process.env | ✅ | ✅ |
| Encrypt secrets | ❌ | ✅ |
| Commit to git safely | ❌ | ✅ |
| File layering | ❌ | ✅ |
| Auto-detection | ❌ | ✅ |
| Native performance | ❌ | ✅ (Rust) |

Requirements

- Node.js >= 18.0.0
- Valid age encryption key (set via environment variable or key file)

Building from Source

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
``

License

MIT - See
LICENSE

Links

- GitHub Repository
- Rust Crate
- Rust Documentation
- Main README