dotenvx - secure environment variable management with encryption. Use for encrypting .env files, multi-environment configuration, cross-platform secret management, and migrating from plaintext dotenv.
Instrucciones de origen · Vista previa de solo lectura
name
dotenvx
version
1.0.0
description
dotenvx - secure environment variable management with encryption. Use for encrypting .env files, multi-environment configuration, cross-platform secret management, and migrating from plaintext dotenv.
dotenvx Skill
dotenvx is a secure dotenv from the creator of the original dotenv package. It adds encryption, multi-environment support, and cross-platform compatibility to environment variable management. Think of it as "dotenv with encryption" - your secrets are encrypted at rest and can be safely committed to version control.
Core Value Proposition: Encrypt your .env files so they can be safely committed to git, while keeping decryption keys separate and secure.
When to Use This Skill
This skill should be triggered when:
Setting up secure environment variable management
Encrypting .env files for version control
Managing secrets across multiple environments (dev, staging, production)
Migrating from plaintext .env to encrypted secrets
Deploying applications with encrypted configuration
# Set a variable (encrypts automatically)
dotenvx set HELLO World
# Set in specific environment
dotenvx set HELLO production -f .env.production
# Set from stdin (for sensitive values)echo"supersecret" | dotenvx set API_KEY
get - Retrieve Variable Values
# Get single variable
dotenvx get HELLO
# Get from specific file
dotenvx get HELLO -f .env.production
# Get all variables as JSON
dotenvx get --all --format json
keypair - Manage Encryption Keys
# Show public/private key pair
dotenvx keypair
# Show for specific environment
dotenvx keypair -f .env.production
Multi-Environment Setup
Recommended Structure
project/
├── .env # Development (encrypted)
├── .env.production # Production (encrypted)
├── .env.staging # Staging (encrypted)
├── .env.local # Local overrides (not committed)
├── .env.keys # All private keys (NEVER commit)
└── .gitignore
.gitignore Configuration
# Never commit private keys
.env.keys
# Never commit local overrides
.env.local
.env.*.local
# DO commit encrypted .env files
# (remove these from .gitignore if present)
# .env
# .env.production
# .env.staging
Environment-Specific Keys
Each environment gets its own key pair:
# .env.keys after encrypting multiple environments
DOTENV_PRIVATE_KEY="ec9d6..."# For .env
DOTENV_PRIVATE_KEY_PRODUCTION="a]c8..."# For .env.production
DOTENV_PRIVATE_KEY_STAGING="3d5f..."# For .env.staging
Loading Order with Conventions
# Next.js convention loads in this order:# .env.local → .env.development → .env
dotenvx run --convention=nextjs -- npm run dev
Integration Examples
Node.js Application
package.json:
{"scripts":{"dev":"dotenvx run -- node index.js","start":"dotenvx run -f .env.production -- node index.js"}}
index.js:
// Option 1: Use dotenvx as drop-in replacementrequire('@dotenvx/dotenvx').config()
console.log(process.env.HELLO)
// Option 2: Use dotenvx.get() for explicit accessconst dotenvx = require('@dotenvx/dotenvx')
dotenvx.config()
console.log(dotenvx.get('HELLO'))
Next.js
package.json:
{"scripts":{"dev":"dotenvx run --convention=nextjs -- next dev","build":"dotenvx run -f .env.production -- next build","start":"dotenvx run -f .env.production -- next start"}}
Docker
Dockerfile:
FROM node:20-alpine
# Install dotenvx
RUN curl -sfS https://dotenvx.sh | sh
WORKDIR /app
COPY . .
RUN npm install
# Run with dotenvx (provide DOTENV_PRIVATE_KEY at runtime)
CMD ["dotenvx", "run", "--", "node", "index.js"]
# Reference other variables
BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v1
# Default values
PORT=${PORT:-3000}# Alternate if set
DEBUG_MODE=${DEBUG:+enabled}
#/-------------------[DOTENV_PUBLIC_KEY]--------------------/#/ public-key encryption for .env files /#/ [how it works](https://dotenvx.com/encryption) /#/----------------------------------------------------------/
DOTENV_PUBLIC_KEY="034a..."# Encrypted values
HELLO="encrypted:BE9Y5L3OxAOOmfq..."
API_KEY="encrypted:CGY8BDMHfq..."
Security Best Practices
Key Management
Never commit .env.keys - Add to .gitignore immediately
Store private keys in secrets manager - GitHub Secrets, Vercel Env, AWS SSM
Rotate keys periodically - Re-encrypt with new keys
Use environment-specific keys - Different keys for dev/staging/production
CI/CD Security
# Set private key as environment variableexport DOTENV_PRIVATE_KEY_PRODUCTION="your-private-key"# dotenvx automatically uses it for decryption
dotenvx run -f .env.production -- npm run build
Team Workflow
# Developer 1: Encrypts new secret
dotenvx set NEW_API_KEY "secret123"
git add .env
git commit -m "Add NEW_API_KEY (encrypted)"
git push
# Developer 2: Pulls and runs (has .env.keys locally)
git pull
dotenvx run -- npm run dev # Works automatically
Sharing Keys Securely
# Option 1: Secure channel (1Password, Signal, etc.)cat .env.keys | pbcopy # Copy to clipboard# Option 2: In-person/video call# Option 3: Company secrets manager# Store DOTENV_PRIVATE_KEY in vault
Cause: Wrong private key or corrupted encrypted value
Solution:
# Verify key matches
dotenvx keypair -f .env.production
# Re-encrypt if needed
dotenvx decrypt -f .env.production # If you have the right key
dotenvx encrypt -f .env.production
Variables Not Loading
# Debug: Show what dotenvx is loading
dotenvx run --debug -- node -e "console.log(process.env)"# Check file is being read
dotenvx run -f .env.production --verbose -- echo"loaded"
Encrypted Values in Wrong File
# Check which file has encrypted values
grep "encrypted:" .env*
# Ensure matching .env.keys entriescat .env.keys
