DotSecrets

Beyond environment variables: a complete secrets ecosystem for local development and cloud production.


The next generation of environment variables management. DotSecrets takes everything you love about dotenv and supercharges it for modern applications. Use local files during development and seamlessly connect to any secrets provider in production – all with zero code changes.

DotSecrets = dotenv + external providers + validation + type safety + encryption + IDE autocompletion

Key Features ✨ Drop-in dotenv replacement with superpowers 🚀 Local to cloud with zero code changes 🛡️ Prevent app crashes from missing secrets 🔄 Auto-convert strings to numbers, booleans, JSON 💡 Never mistype a secret name again 🔌 AWS, Azure, ByteHide, HashiCorp — one command 🔒 Push secrets securely to production

📋 Table of Contents

- 1. 🌱 Install
- 2. 🚀 Getting Started
- 3. 🔄 Migrating from dotenv
- 4. 🏗️ Core Features
- Multiple ENV Files
- Environment-Specific Files
- Push Secrets to Production
- Asynchronous-First Approach
- Powerful Validation \& Type Conversion
- External Secrets Providers
- Zero-code production configuration
- Variable Expansion
- Public Secrets
- Auto-reloading \& File Watching
- IDE Autocompletion
- Encryption Support
- 5. 🔌 Secrets Providers
- Provider Configuration
- Environment Variables (Default)
- ByteHide Secrets
- AWS Secrets Manager
- Azure Key Vault
- Google Cloud Secret Manager
- HashiCorp Vault
- IBM Cloud Secrets Manager
- 1Password
- Keeper Secrets Manager
- Doppler
- 6. 🛠️ Common Usage Patterns
- 7. ⚙️ Configuration
- 8. 🛠️ CLI Tools
- 9. 🔬 Advanced Usage
- 10. ❓ FAQ \& Troubleshooting
- 11. 📚 API Reference
- 12. 💪 Contributing & Community

1. 🌱 Install

``bash


npm

`javascript
// Just import the secrets object and start using it
import { secrets } from 'dotsecrets';

// RECOMMENDED: Always use the async pattern with await
async function getApiClient() {
const endpoint = await secrets.API_ENDPOINT;
const key = await secrets.API_KEY.required();

return new ApiClient(endpoint, key);
}
`

$3

If you don't have .env or .secrets files yet, you can easily set them up:

`bash


Creates .env, .secrets, and adds them to .gitignore

`javascript
// ❌ NOT needed with DotSecrets
// import dotenv from 'dotenv';
// dotenv.config();

// ✅ Just import and use
import { secrets } from 'dotsecrets';
`

$3

Always use the asynchronous pattern with await for the most reliable access to your secrets:

`javascript
// ✅ Recommended: Async pattern
const apiKey = await secrets.API_KEY;
const isDebug = await secrets.DEBUG_MODE.boolean();
const serverPort = await secrets.PORT.number().min(1000);

// ❌ Avoid using the synchronous pattern unless absolutely necessary
// const apiKey = secrets.API_KEY; // Not recommended without preloadAllSecrets()
`

$3

Only in cases where async/await cannot be used, you can preload secrets at application startup:

`javascript
import { preloadAllSecrets, secrets } from 'dotsecrets';

// At application startup:
await preloadAllSecrets();

// Then in synchronous code:
function getLegacyConfig() {
return secrets.API_KEY; // Works after preloading
}
`

3. 🔄 Migrating from dotenv

Already using dotenv? DotSecrets makes it easy to upgrade to a more powerful secrets management solution while maintaining compatibility.

!DotSecrets Autocomplete

$3

You can quickly migrate from dotenv to DotSecrets using the migrate command:

`bash
npx dotsecrets migrate
`

This command:

- Handles your existing .env files
- Sets up DotSecrets configuration
- Adds appropriate entries to .gitignore
- Generates TypeScript definitions for IDE autocompletion

$3

DotSecrets maintains full compatibility with process.env, so your existing code will continue to work:

`javascript
// This still works - no changes needed for existing code
const apiUrl = process.env.API_URL;
`

All variables from .env, .secrets, and .public files are automatically loaded into process.env, just like with dotenv.

$3

While DotSecrets maintains compatibility with process.env, you gain significant advantages by migrating to the secrets.KEY pattern:

| Feature | process.env.KEY | secrets.KEY |
|---------|-----------------|-------------|
| Type safety | ❌ Always string or undefined | ✅ Type conversion (number, boolean, JSON) |
| Validation | ❌ Manual validation required | ✅ Built-in validation chains |
| Error handling | ❌ Silent undefined errors | ✅ Clear error messages |
| Asynchronous loading | 🫠 Don't apply | ✅ Async providers supported |
| Default values | ❌ Manual defaulting | ✅ Built-in .default() method |
| IDE autocompletion | ❌ No key suggestions | ✅ Full autocompletion support |
| Production-ready | ❌ Local-only solution | ✅ Seamless transition to cloud providers |
| Provider switching | ❌ Code changes required | ✅ Zero code changes when switching providers |
| Frontend access | ❌ Not available in browser | ✅ secrets.PUBLIC_* works in frontend code |

#### Production-ready secret management

Using secrets.KEY makes your application immediately ready for production environments:

`javascript
// Your code stays EXACTLY THE SAME when moving from development to production
async function getApiClient() {
const apiKey = await secrets.API_KEY.required();
// ...
}
`

You can start with local .env files during development, then seamlessly switch to AWS Secrets Manager, Azure Key Vault, ByteHide Secrets, Google Cloud Secret Manager, or any other provider in production - without changing a single line of application code. DotSecrets handles the provider configuration separately from your business logic.

#### Seamless provider switching

With process.env:

`javascript
// Hard-coded to use environment variables
const apiKey = process.env.API_KEY;
// Must rewrite code to use a different provider
`

With DotSecrets:

`javascript
// Works with ANY provider - local files, ByteHide, Azure, AWS, Google Cloud, etc.
const apiKey = await secrets.API_KEY;
`

Simply configure your preferred provider with npx dotsecrets setup and your application will automatically retrieve secrets from the right source, regardless of environment.

$3

Before (with dotenv):

`javascript
// Manual validation, type conversion, and error handling
const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
if (isNaN(port) || port < 1000 || port > 9999) {
throw new Error('PORT must be a number between 1000 and 9999');
}

const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('API_KEY is required');
}
`

After (with DotSecrets):

`javascript
// Built-in validation, type conversion, and error handling
const port = await secrets.PORT.number().between(1000, 9999).default(3000);
const apiKey = await secrets.API_KEY.required();
`

4. 🏗️ Core Features

$3

!DotSecrets Workflow Schema

DotSecrets manages different types of configuration files:

| File | Purpose | In Git? | Example Values |
|------|---------|---------|---------------|
| .secrets | Sensitive information | ❌ No | Passwords, API keys, tokens |
| .env | Development variables | ❌ No | Local hostnames, debug flags |
| .public | Non-sensitive config | ✅ Yes | Public URLs, feature flags (with PUBLIC_ prefix) |

> ⚠️ Note: Using .secrets is optional - you can continue using .env files like with dotenv. However, the separate files provide better organization: .secrets clearly indicates sensitive information, .env can contain mixed values, and .public explicitly marks values safe for version control. This naming convention helps prevent accidental exposure of sensitive data.

$3

Automatically load environment-specific configurations:

`bash
.secrets # Base secrets for all environments
.secrets.staging # Overrides for staging environment
.secrets.production # Overrides for production
`

> The same with .env and .public files

Set your environment with NODE_ENV or explicitly in configuration.

$3

!DotSecrets Push

DotSecrets makes it easy to sync your local secrets to production environments without ever exposing them in version control:

`bash
npx dotsecrets push
`

This interactive command:

1. Scans for all available .secrets and .env files
2. Lets you select which file to push from
3. Allows you to exclude specific secrets from being pushed
4. Guides you through selecting a destination provider (AWS, Azure, ByteHide, etc.)
5. Securely uploads your secrets to the selected provider

This seamless workflow ensures your development and production environments stay in sync while maintaining the highest security standards - your secrets never need to pass through git or any other intermediary.

$3

DotSecrets is designed with modern JavaScript in mind:

`javascript
// RECOMMENDED: Clean async access pattern
async function initializeApi() {
const endpoint = await secrets.API_ENDPOINT;
const key = await secrets.API_KEY.required();
const timeout = await secrets.TIMEOUT.number().default(5000);

return new ApiClient(endpoint, key, { timeout });
}

// Only for legacy code: Synchronous access pattern
// Requires preloading secrets at application startup
if (needsSynchronousAccess) {
await preloadAllSecrets();
const apiKey = secrets.API_KEY; // Only works after preload
}
`

$3

Ensure your secrets meet your requirements:

`javascript
// Convert to number with range validation
const port = await secrets.PORT.number().between(1000, 9999);

// Required values
const apiKey = await secrets.API_KEY.required();

// String validation
const email = await secrets.EMAIL.trim().regex(/^[\w.-]+@[\w.-]+\.\w+$/);

// Boolean conversion with validation
const enabled = await secrets.FEATURE_FLAG.boolean().true();

// JSON parsing with type safety
const config = await secrets.CONFIG.json();
`

$3

Connect to external providers with simple configuration:

- Environment variables (built-in)
- ByteHide Secrets
- AWS Secrets Manager
- Azure Key Vault
- Google Cloud Secret Manager
- HashiCorp Vault
- 1Password
- And more...

#### Zero-code production configuration

In production environments, you can automatically load secrets from external providers without changing your code. Simply set environment variables to configure the provider:

`bash


Example: Use IBM Cloud Secrets Manager in production

Your application will automatically load secrets from the configured provider in production while continuing to use local .env and .secrets files in development – all without changing a single line of code.

> 🔗 See all available providers and their configuration options
>


$3

DotSecrets supports referencing other variables within your configuration:

`bash


Variable references are automatically expanded

`javascript
config({ expand: true });
`

Or just set DOTSECRETS_EXPAND=true in your environment.

$3

Values prefixed with PUBLIC_ are considered non-sensitive and can be safely exposed to frontend code:

`bash


.public file (can be committed to git)

- Can be stored in the .public file (safe to commit to git)
- Are always loaded locally, never from external providers
- Can be accessed synchronously without await (even without preload)

`javascript
// Access public values without await
const apiVersion = secrets.PUBLIC_API_VERSION;
const features = secrets.PUBLIC_FEATURE_FLAGS.json();

// In frontend code
console.log("Using API version:", secrets.PUBLIC_API_VERSION);
`

$3

Automatically detect changes to configuration files in development:

`javascript
// Enable file watching
config({ watch: true });
`

When changes are detected, secrets are reloaded and optional update scripts are executed.

$3

!DotSecrets Autocomplete

Generate TypeScript definitions for your secrets:

`bash


Generate type definitions for IDE autocompletion

DotSecrets includes support for encrypting .secrets files:

`javascript
// Load with encryption key
config({ encryptionKey: process.env.DOTSECRETS_ENCRYPTION_KEY });
`

> Note: While encryption is available, we recommend using dedicated secrets management providers rather than storing encrypted secrets in version control. The push command provides a more secure way to synchronize secrets between environments without exposing them, even in encrypted form.
>
> For production environments, consider services like AWS Secrets Manager, Azure Key Vault, ByteHide Secrets, or HashiCorp Vault, which offer additional security features such as access auditing, rotation policies, and fine-grained permissions.

5. 🔌 Secrets Providers

DotSecrets supports multiple secrets providers, allowing you to store your secrets in different systems while maintaining a consistent access pattern in your code.

> ⚠️ Important Warning: Local variables in .env or .secrets files always take precedence over external providers. If you want to retrieve a secret like API_KEY from AWS Secrets Manager (or any other provider), make sure you do not define that same variable in your local .env or .secrets files, and do not deploy these files to production servers. If the variable exists locally, it will override the one from your configured provider, which can lead to unexpected behavior in production environments.

$3

| Provider | Plugin ID | Type | Support |
|----------|-----------|------|---------|
| Environment Variables | env | Local | ✅ |
| ByteHide Secrets | bytehide | Cloud | ✅ |
| AWS Secrets Manager | aws | Cloud | ✅ |
| Azure Key Vault | azure | Cloud | ✅ |
| Google Cloud Secret Manager | gcp | Cloud | ✅ |
| HashiCorp Vault | hashicorp | Self-hosted/Cloud | ✅ |
| IBM Cloud Secrets Manager | ibm | Cloud | ✅ |
| 1Password | onepassword | Cloud | ✅ |
| Keeper Secrets Manager | keeper | Cloud | ✅ |
| Doppler | doppler | Cloud | ✅ |
| CyberArk Conjur | cyberark | Self-hosted/Cloud | Coming soon |
| Akeyless Vault | akeyless | Cloud | Coming soon |

> 🔌 Looking for a different provider? We're constantly expanding our support for secrets management systems. Open an issue in our GitHub repository describing the provider you need, or submit a pull request implementing a new provider by following our contribution guidelines.

$3

Each provider has specific configuration requirements. The easiest way to configure a provider is using the setup command:

`bash
npx dotsecrets setup
`

Alternatively, you can configure providers manually by setting the appropriate environment variables:

#### Environment Variables (Default)

No configuration needed - works out of the box.

#### ByteHide Secrets

`bash
DOTSECRETS_PLUGIN=bytehide
BYTEHIDE_SECRETS_TOKEN=your-token
BYTEHIDE_SECRETS_ENVIRONMENT=production
`

#### AWS Secrets Manager

`bash
DOTSECRETS_PLUGIN=aws
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
`

#### Azure Key Vault

`bash
DOTSECRETS_PLUGIN=azure
AZURE_KEYVAULT_URI=https://your-vault.vault.azure.net
AZURE_CLIENT_ID=your-client-id
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_SECRET=your-client-secret
`

#### Google Cloud Secret Manager

`bash
DOTSECRETS_PLUGIN=gcp
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json


Or use credential object directly

`bash
DOTSECRETS_PLUGIN=hashicorp
VAULT_ADDR=https://your-vault-instance:8200
VAULT_TOKEN=your-vault-token
`

HCP Cloud option:

`bash
DOTSECRETS_PLUGIN=hashicorp
HCP_CLIENT_ID=your-client-id
HCP_CLIENT_SECRET=your-client-secret
HCP_ORG_ID=your-org-id
HCP_PROJECT_ID=your-project-id
HCP_APP_NAME=your-app-name
`

#### IBM Cloud Secrets Manager

`bash
DOTSECRETS_PLUGIN=ibm
IBM_CLOUD_API_KEY=your-api-key
IBM_SECRETS_MANAGER_URL=your-instance-url
`

#### 1Password

`bash
DOTSECRETS_PLUGIN=onepassword
OP_CONNECT_HOST=your-connect-server-url
OP_CONNECT_TOKEN=your-connect-token
OP_VAULT=your-vault-name
`

#### Keeper Secrets Manager

`bash
DOTSECRETS_PLUGIN=keeper
KEEPER_CONFIG_FILE=/path/to/your/config.json
KEEPER_FOLDER_UID=your-folder-uid
`

#### Doppler

`bash
DOTSECRETS_PLUGIN=doppler
DOPPLER_TOKEN=your-doppler-token
DOPPLER_PROJECT=your-project-name
DOPPLER_CONFIG=your-config-name
`

$3

DotSecrets determines which provider to use in the following order:

1. DOTSECRETS_PLUGIN environment variable
2. Configuration in dotsecrets.config.json
3. Defaults to environment variables if no provider is specified

$3

DotSecrets includes built-in performance optimizations for production environments:

- Automatic caching: Secrets retrieved from external providers are automatically cached in memory to minimize API calls.
- Batch loading: When possible, DotSecrets retrieves multiple secrets in a single network request.
- Parallel requests: For providers that don't support batch loading, DotSecrets uses concurrent requests with rate limiting.

This ensures high performance in production environments while maintaining minimal network overhead, even when accessing dozens or hundreds of secrets.

$3

Typical workflow between environments:

`javascript
// Development: Uses local .env and .secrets files
// No special configuration needed

// Production: Set the provider via environment variables
// DOTSECRETS_PLUGIN=bytehide
// BYTEHIDE_SECRETS_TOKEN=your-bytehide-token

// Your code stays EXACTLY THE SAME
async function getDatabase() {
// Works with ANY provider
const connectionString = await secrets.DATABASE_URL.required();
return createConnection(connectionString);
}
`

6. 🛠️ Common Usage Patterns

DotSecrets provides numerous validation and transformation methods to ensure your secrets meet your requirements.

$3

`javascript
// Ensure a secret exists
const apiKey = await secrets.API_KEY.required();

// Check that a secret is not empty
const username = await secrets.USERNAME.notEmpty();

// Trim whitespace
const email = await secrets.EMAIL.trim();

// String length validation
const password = await secrets.PASSWORD.lengthBetween(8, 100);
`

$3

`javascript
// Convert to number
const port = await secrets.PORT.number();

// Convert to boolean (true for: "true", "yes", "1", "on")
const debugMode = await secrets.DEBUG_MODE.boolean();

// Parse JSON with type safety
const config = await secrets.CONFIG.json();
const serverSettings = await secrets.SETTINGS.json();
`

$3

When a secret might not exist, you can provide defaults:

`javascript
// Use default if secret doesn't exist
const timeout = await secrets.TIMEOUT.default("5000");

// With type conversion
const maxRetries = await secrets.MAX_RETRIES.number().default(3);
const isFeatureEnabled = await secrets.FEATURE_ENABLED.boolean().default(false);
`

$3

Chain multiple validations together for complex requirements:

`javascript
// Number validation chain
const serverPort = await secrets.PORT
.number() // Convert to number
.required() // Must exist
.min(1024) // Must be >= 1024
.max(65535); // Must be <= 65535

// String validation chain
const emailAddress = await secrets.EMAIL
.trim() // Remove whitespace
.required() // Must exist
.regex(/^[\w.-]+@[\w.-]+\.\w+$/); // Must match pattern

// Boolean with validation
const featureFlag = await secrets.FEATURE_FLAG
.boolean() // Convert to boolean
.required() // Must exist
.true(); // Must be true
`

$3

Apply transformations to secret values:

`javascript
// Case transformations
const countryCode = await secrets.COUNTRY_CODE.toUpperCase();
const username = await secrets.USERNAME.toLowerCase();

// JSON transformation with validation
const config = await secrets.CONFIG
.json()
.required();
`

$3

Handle validation errors gracefully:

`javascript
try {
const apiKey = await secrets.API_KEY.required();
// Use apiKey...
} catch (error) {
// Handle specific validation error
console.error("API key missing:", error.message);
// Fallback or exit gracefully
}
`

$3

Create middleware to ensure required secrets exist:

`javascript
function requireSecrets(...secretKeys) {
return async (req, res, next) => {
try {
for (const key of secretKeys) {
// This will throw if any secret is missing
await secrets[key].required();
}
next();
} catch (error) {
res.status(500).json({
error: Missing required secret: ${error.message}
});
}
};
}

// Use middleware on routes that need specific secrets
app.get('/api/data',
requireSecrets('API_KEY', 'DATABASE_URL'),
(req, res) => {
// All required secrets exist
// Your route handler...
}
);
`

7. ⚙️ Configuration

DotSecrets is designed to work with zero configuration, but offers extensive customization options when needed.

$3

The recommended way to configure DotSecrets is through a JSON configuration file. Create a file named dotsecrets.config.json in your project root:

`json
{
"path": ".secrets",
"envPath": ".env",
"environment": "development",
"watch": true,
"expand": true,
"debug": false,
"override": false
}
`

DotSecrets will automatically discover and load this file. Alternatively, you can place it in:

- .dotsecrets.config.json
- config/dotsecrets.config.json

$3

DotSecrets loads configuration from multiple sources, with the following priority (highest to lowest):

1. Explicit parameters in code: config({ watch: true })
2. Environment variables: DOTSECRETS_WATCH=true
3. Configuration file: dotsecrets.config.json
4. Default values

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| path | string | .secrets | Path to the secrets file |
| envPath | string | .env | Path to the environment file |
| environment | string | process.env.NODE_ENV | Environment name for loading specific files |
| encoding | string | utf8 | File encoding for reading config files |
| watch | boolean | true in development | Watch files for changes and reload |
| debug | boolean | false | Enable debug logging |
| override | boolean | false | Override existing environment variables |
| expand | boolean | false | Expand variable references like ${VAR} |
| encryptionKey | string | process.env.DOTSECRETS_ENCRYPTION_KEY | Key for decrypting encrypted secrets |
| autoInit | boolean | true | Automatically initialize on import |
| skipAutoConfig | boolean | false | Skip automatic configuration |

$3

All options can also be set using environment variables:

`bash


Configuration via environment variables

`javascript
import { config } from 'dotsecrets';

// Override configuration programmatically
const loadedSecrets = config({
path: './config/secrets/.secrets',
environment: 'staging',
watch: true,
expand: true,
debug: process.env.DEBUG === 'true'
});

console.log(Loaded ${Object.keys(loadedSecrets).length} secrets);
`

$3

DotSecrets can automatically reload secrets when configuration files change and execute custom scripts:

`javascript
// Enable file watching (default in development)
config({ watch: true });
`

When a watched file changes, DotSecrets will:

1. Reload all secrets automatically
2. Execute reload hooks in the following order:

#### Custom Reload Hooks

Define a script in your package.json:

`json
{
"scripts": {
"onSecretsUpdate": "node scripts/reload-app.js"
}
}
`

Or create a standalone script file in your project root:

- dotSecretsUpdate.js
- dotSecretsUpdate.ts

These scripts will be executed whenever your secrets change, allowing you to:

- Restart server components
- Clear caches
- Notify systems of configuration changes
- Update connected clients

$3

Here's a complete example with custom configuration:

`javascript
// In your application entry point
import { config } from 'dotsecrets';

// Load configuration with custom settings
config({
// Custom file paths
path: './config/secrets/.secrets',
envPath: './config/env/.env',

// Use production environment explicitly
environment: 'production',

// Enable variable expansion
expand: true,

// Enable file watching in development
watch: process.env.NODE_ENV !== 'production',

// Enable debugging in development
debug: process.env.NODE_ENV !== 'production',

// Use encryption key from environment
encryptionKey: process.env.SECRET_KEY
});
`

For most applications, the zero-configuration approach is sufficient, with DotSecrets automatically loading configuration from files and environment variables.

8. 🛠️ CLI Tools

DotSecrets includes several command-line tools to simplify setup, migration, and integration with your development environment.

$3

The setup command helps you initialize and configure DotSecrets in your project:

`bash
npx dotsecrets setup
`

This interactive wizard:

1. Creates necessary configuration files (.secrets, .env, .public) if they don't exist
2. Updates your .gitignore to exclude sensitive files
3. Guides you through configuring a secrets provider (ByteHide, AWS, Azure, etc.)
4. Sets up required environment variables for your chosen provider

Options:

- --path - Specify a folder path (default: current directory)

$3

The push command enables you to securely transfer your local secrets to any supported production provider:

`bash
npx dotsecrets push
`

This interactive tool:

1. Scans your project for .secrets and .env files
2. Allows you to select which file contains the secrets to push
3. Lets you choose specific secrets to include or exclude
4. Presents a list of available secrets providers (AWS, Azure, ByteHide, etc.)
5. Securely uploads your selected secrets to the chosen provider

This command provides a secure bridge between development and production environments without ever exposing secrets in version control, making it easy to maintain consistent configurations across all environments.

Options:

- --path - Specify a folder path to scan (default: current directory)

$3

The migrate command helps you transition from dotenv to DotSecrets:

`bash
npx dotsecrets migrate
`

This comprehensive migration tool:

1. Scans for existing .env files and converts them to .secrets equivalents
2. Transforms process.env.X references in your code to secrets.X
3. Removes dotenv configuration code from your project
4. Optionally uninstalls the dotenv package

Options:

- --path - Specify a folder path to scan (default: current directory)

$3

The sync-ide command generates TypeScript definitions for IDE autocompletion:

`bash
npx dotsecrets sync-ide
`

This tool:

1. Scans your project for all available secrets
2. Generates TypeScript definition files for enhanced IDE experience
3. Creates complete type definitions for the secrets object and all validation methods
4. Supports both TypeScript and JavaScript files with JSDoc annotations

Options:

- --outDir