Get secrets from AWS secret manager and merge them with ENV configs
npm install mysterioUnified configuration management for Node.js applications
Mysterio combines your local config files and AWS Secrets Manager into a single, easy-to-use configuration object. No more juggling multiple configuration sources or worrying about where your settings live - everything is merged intelligently at runtime.
See the Migration Guide for detailed instructions on upgrading from v2.x to v3.0.
config/production.json)Mysterio merges them at runtime into one config object. That's it!
``
default.json -> env.json -> secrets (AWS) -> .mysteriorc
(optional) (required) (required) (optional)
Core (required):
- env.json - Environment-specific configs (production.json, dev.json, etc.)
- secrets - Secure values from AWS Secrets Manager
Optional layers:
- default.json - Base configs shared across all environments
- .mysteriorc - Local developer overrides (gitignored)
Each layer overrides values from the previous layers, allowing you to:
- Define base configs that work everywhere (optional)
- Set environment-specific settings (required)
- Add secure secrets from AWS Secrets Manager (required)
- Use local overrides for development (optional)
Simple Example (env + secrets only):
`json
// config/production.json
{
"database": {
"host": "prod-db.example.com",
"port": 5432
},
"apiUrl": "https://api.production.com"
}
// AWS Secrets Manager (myapp/production)
{
"database": {
"password": "super-secret-password",
"username": "dbuser"
},
"apiKey": "secret-api-key"
}
// Final merged result:
{
"database": {
"host": "prod-db.example.com", // from production.json
"port": 5432, // from production.json
"username": "dbuser", // from AWS Secrets
"password": "super-secret-password" // from AWS Secrets
},
"apiUrl": "https://api.production.com", // from production.json
"apiKey": "secret-api-key" // from AWS Secrets
}
`
Advanced Example (with all optional layers):
`json
// config/default.json (optional - base for all environments)
{
"database": {
"port": 5432
},
"apiUrl": "http://localhost:3000"
}
// config/production.json (required - environment specific)
{
"database": {
"host": "prod-db.example.com"
},
"apiUrl": "https://api.production.com"
}
// AWS Secrets Manager (required - secrets)
{
"database": {
"password": "super-secret-password"
}
}
// .mysteriorc (optional - local overrides, gitignored)
{
"database": {
"host": "127.0.0.1"
}
}
// Final merged result with all layers:
{
"database": {
"host": "127.0.0.1", // from .mysteriorc (highest priority)
"port": 5432, // from default.json
"password": "super-secret-password" // from AWS Secrets
},
"apiUrl": "https://api.production.com" // from production.json
}
`
- Dynamic secrets - Rotate AWS secrets without redeploying
- Fresh on every start - Always get the latest configuration$3
- Secrets stay in AWS Secrets Manager (never committed to git)
- Local overrides () can be gitignored for developer-specific settings
- Supports AWS IAM roles and secure credential managementInstallation
`bash
npm install mysterio
`š Quick Start
The simplest setup only requires environment configs and AWS secrets.
$3
your-project/
āāā config/
ā āāā production.json # Production settings (required)
ā āāā dev.json # Dev environment (optional)
ā āāā local.json # Local development (optional)
āāā package.json
Optional files:
-
- Base configs for all environments
- .mysteriorc - Local developer overrides (gitignore this!)$3
config/production.json:
`json
{
"appName": "MyApp",
"port": 8080,
"database": {
"host": "prod-db.example.com",
"port": 5432
},
"apiUrl": "https://api.production.com"
}
`config/local.json (for local development):
json
{
"appName": "MyApp",
"port": 3000,
"database": {
"host": "localhost",
"port": 5432
},
"apiUrl": "http://localhost:3000"
}
`$3
Create a secret in AWS Secrets Manager with the name pattern:
For example, if your package.json has
and you're running in production:
- Secret name: myapp/production#### āØ Option A: Using the Key/value Tab (Recommended)
AWS Secrets Manager doesn't support JSON validation in the plaintext editor, which can lead to invalid JSON being saved. Instead, it's much more convenient to use the Key/value tab when creating or editing secrets. Mysterio can automatically unflatten these key-value pairs into nested objects:
In AWS Console (Key/value tab):
database.password = super-secret-password
database.username = dbuser
apiKey = your-secret-api-key
In your code (with unflatten enabled):
javascript
const config = await mysterio.getMerged(['default', 'env', 'secrets', 'rc'], true)
// Secrets are automatically unflattened to:
// {
// database: {
// password: 'super-secret-password',
// username: 'dbuser'
// },
// apiKey: 'your-secret-api-key'
// }
`#### š Option B: Using JSON (Plaintext Tab)
You can still use traditional JSON format in the plaintext editor:
Secret value:
json
{
"database": {
"password": "super-secret-password",
"username": "dbuser"
},
"apiKey": "your-secret-api-key"
}
`$3
javascript
import { Mysterio } from 'mysterio'const mysterio = new Mysterio()
const config = await mysterio.getMerged()
console.log(config)
// {
// appName: 'MyApp',
// port: 8080,
// database: {
// host: 'prod-db.example.com',
// port: 5432,
// username: 'dbuser',
// password: 'super-secret-password'
// },
// apiKey: 'your-secret-api-key'
// }
// Use your config
const db = await connectToDatabase(config.database)
`API
$3
Creates a new Mysterio instance.
Options:
-
(string): Path to config directory. Default: ./config
- (string): Path to local RC file. Default: ./.mysteriorc
- (string): Custom AWS secret name. Default: {package-name}/{NODE_ENV || 'local'}
- (string): Override environment name instead of using NODE_ENV. Affects both config file selection and secret name generation
- awsParams (object): AWS SDK parameters for Secrets Manager client
- client (function): Custom client function for fetching secretsExample:
`javascript
const mysterio = new Mysterio({
configDirPath: './my-configs',
localRcPath: './.myapprc',
secretName: 'custom-secret-name',
env: 'staging', // Use staging configs regardless of NODE_ENV
awsParams: {
region: 'us-west-2'
}
})
`$3
Returns the merged configuration object.
Parameters:
-
(array): Custom merge order. Default: ['default', 'env', 'secrets', 'rc']
- (boolean): Whether to unflatten dotted secret keys into nested objects. Default: falseReturns: Promise
Example:
javascript
// Default order with flat secrets
const config = await mysterio.getMerged()// With unflattened secrets (recommended for AWS Key/value tab)
const config = await mysterio.getMerged(['default', 'env', 'secrets', 'rc'], true)
// Custom order - secrets override everything
const config = await mysterio.getMerged(['default', 'env', 'rc', 'secrets'])
// Partial config - only default and env
const config = await mysterio.getMerged(['default', 'env'])
`$3
####
Returns the default config from ####
Returns environment-specific config based on (e.g., config/production.json)####
mysterio.getRcConfigs()
Returns local RC file config from ####
Returns secrets from AWS Secrets ManagerParameters:
-
(boolean): Whether to unflatten dotted keys into nested objects. Default: falseExample:
javascript
// Get secrets as flat key-value pairs
const secrets = await mysterio.getSecrets(false)
// { 'database.password': 'secret', 'database.username': 'user' }// Get secrets with dotted keys unflattened into nested objects
const secrets = await mysterio.getSecrets(true)
// { database: { password: 'secret', username: 'user' } }
`Configuration Sources
$3
#### Environment Config (
)
Environment-specific configuration based on NODE_ENV (or the env constructor option):
- NODE_ENV=production -> config/production.json
- -> config/development.json
- -> config/test.json
- Not set ->
- in constructor -> config/staging.json (overrides NODE_ENV)This is where your non-sensitive settings live (ports, hosts, feature flags, etc.)
#### Secrets (AWS Secrets Manager)
Secure secrets stored in AWS, automatically fetched based on:
- Package name from
package.json
- Current environment ( or the env constructor option)
- Pattern: {package-name}/{environment}This is where your sensitive data lives (passwords, API keys, tokens, etc.)
$3
#### Default Config (
) - OPTIONAL
Base configuration that applies to all environments. Use this to avoid duplicating common settings across environment files.If you don't need shared base configs, you can skip this file entirely.
#### RC File (
.mysteriorc) - OPTIONAL
Local developer overrides (should be gitignored). Perfect for:
- Database connections to local instances
- API endpoints pointing to localhost
- Debug flags
- Developer-specific settingsMost projects don't need this - only use it if developers need local overrides.
Advanced Usage
$3
AWS Secrets Manager's Key/value tab is more convenient than the plaintext JSON editor because it doesn't require JSON validation and is easier to edit. However, it stores secrets as flat key-value pairs. Mysterio can automatically unflatten these dotted keys into nested objects.
āØ Why use the Key/value tab?
- ā ļø AWS Secrets Manager doesn't support JSON validation in the plaintext editor
- š„ Invalid JSON can be accidentally saved, breaking your application
- šÆ The Key/value tab provides a better UI for managing individual secrets
- ā” Easier to add, remove, or update individual values
How it works:
When you enable unflattening, Mysterio converts dotted keys like
database.password into nested objects:`javascript
// AWS Secrets (Key/value tab):
// database.host = prod-db.example.com
// database.port = 5432
// database.credentials.password = secret123
// database.credentials.username = dbuser
// apiKey = my-api-key// With unflatten enabled:
const config = await mysterio.getMerged(['default', 'env', 'secrets'], true)
console.log(config)
// {
// database: {
// host: 'prod-db.example.com',
// port: 5432,
// credentials: {
// password: 'secret123',
// username: 'dbuser'
// }
// },
// apiKey: 'my-api-key'
// }
`š Deep merging with unflattened secrets:
Unflattened secrets merge deeply with your config files:
javascript
// config/production.json
{
"database": {
"host": "prod-db.example.com",
"maxConnections": 100
}
}// AWS Secrets (Key/value tab):
// database.password = secret123
// database.username = dbuser
// With unflatten enabled:
const config = await mysterio.getMerged(['env', 'secrets'], true)
// Result - secrets merge into existing database object:
{
"database": {
"host": "prod-db.example.com",
"maxConnections": 100,
"password": "secret123", // From secrets
"username": "dbuser" // From secrets
}
}
`ā ļø Key Conflicts:
When using the unflatten feature, be aware of how key conflicts are handled. If a parent key already exists as a non-object value, it cannot be converted to accept nested properties. The behavior follows JavaScript object property assignment order:
javascript
// AWS Secrets (Key/value tab):
// database = "connection-string"
// database.host = "localhost"// With unflatten enabled:
const secrets = await mysterio.getSecrets(true)
// Result: The last value wins based on object key order
// If 'database' comes after 'database.host' in the object:
// { database: "connection-string" }
// If 'database.host' comes after 'database':
// { database: "connection-string" }
// Note: 'database.host' is ignored because 'database' is already a string
`š” Best Practice: Avoid conflicts by using consistent naming:
- ā
Use only nested keys:
, database.port, database.password
- ā Don't mix: (as value) and database.host (as nested key)This ensures your secrets unflatten predictably into nested objects.
$3
You can provide your own secret fetching function:
`javascript
const customClient = async (secretName) => {
// Fetch from your own secret management system
return {
apiKey: 'custom-secret'
}
}const mysterio = new Mysterio({
client: customClient
})
`$3
Mysterio uses the debug module. Enable debug logs:
bash
DEBUG=Mysterio:* node your-app.js
`$3
typescript
import { Mysterio } from 'mysterio'interface MyConfig {
database: {
host: string
port: number
password: string
}
apiKey: string
}
const mysterio = new Mysterio()
const config = await mysterio.getMerged() as MyConfig
`š Best Practices
$3
gitignore
.mysteriorc
config/local.json
`$3
javascript
const mysterio = new Mysterio({
configDirPath: process.env.CONFIG_PATH || './config'
})
`$3
javascript
const config = await mysterio.getMerged()if (!config.database?.password) {
throw new Error('Database password not configured!')
}
`$3
- - Local development secrets
- myapp/dev - Development environment
- myapp/staging - Staging environment
- myapp/production - Production environmentš How Merging Works
Mysterio uses lodash.merge for deep merging:
1. Order matters: Later sources override earlier ones
2. Deep merge: Nested objects are merged, not replaced
3. Arrays are replaced: Arrays from later sources completely replace earlier ones
Example:
`javascript
// default.json
{
"features": ["feature1", "feature2"],
"database": { "host": "localhost", "port": 5432 }
}// production.json
{
"features": ["feature3"],
"database": { "host": "prod.db" }
}
// Merged result:
{
"features": ["feature3"], // Replaced (arrays don't merge)
"database": {
"host": "prod.db", // Overridden
"port": 5432 // Kept from default
}
}
`š Environment Detection
The environment is determined by
:`bash
Uses config/production.json and myapp/production secrets
NODE_ENV=production node app.jsUses config/dev.json and myapp/dev secrets
NODE_ENV=dev node app.jsUses config/local.json and myapp/local secrets (default)
node app.js
`$3
You can override the environment detection by passing the
option to the constructor. This is useful when you want to load a specific environment's configuration regardless of the NODE_ENV value:`javascript
// Always use staging config, even if NODE_ENV is production
const mysterio = new Mysterio({
env: 'staging'
})// This will load:
// - config/staging.json (instead of using NODE_ENV)
// - myapp/staging secrets (instead of myapp/production)
`Use cases:
- Testing: Load production configs in a test environment without changing
- Multi-environment apps: Run multiple instances with different configs in the same process
- Config validation: Test different environment configs without modifying environment variables
- CI/CD pipelines: Explicitly specify which environment to use regardless of system settingsCLI Tools
Mysterio includes CLI tools to help manage your configuration and secrets workflow.
$3
After installing mysterio, the CLI is available as
(if installed globally) or via npx mysterio.$3
####
generate-templateGenerate an AWS Secrets Manager template from your config file's
placeholders.`bash
Output to stdout
mysterio generate-template -c ./config/production.jsonOutput to file
mysterio generate-template -c ./config/production.json -o ./secrets-template.json
`Options:
-
(required) - Local config file path
- -o, --output - Output file path (stdout if not specified)Example output:
`json
{
"database.password": "replace_with_secret",
"database.username": "replace_with_secret",
"api.key": "replace_with_secret"
}
`####
Find missing keys between an AWS secret and your local config's placeholders.
bash
Using defaults (reads ./config/{NODE_ENV}.json and {packageName}/{NODE_ENV} secret)
mysterio compare-secretSpecify environment explicitly
mysterio compare-secret -e productionSpecify custom paths
mysterio compare-secret -c ./config/production.json -s myapp/production
`Options:
-
- Local config file path (default: ./config/{env}.json)
- -s, --secret - AWS secret name (default: {packageName}/{env})
- -e, --env - Environment (default: NODE_ENV or "local")
- -r, --region - AWS region (default: us-east-1)
- -o, --output - Output format: text or json (default: text)Exit codes:
-
0 - All placeholders are present in the AWS secret
- 1 - Some placeholders are missing
- 2 - Error occurred####
compare-configsCompare merged configurations between two environments using superdiff.
bash
Compare staging and production configs (without secrets)
mysterio compare-configs --env1 staging --env2 production --sources "default,env"Compare with AWS secrets (uses default {packageName}/{env} pattern)
mysterio compare-configs --env1 staging --env2 productionCompare with custom secret template
mysterio compare-configs --env1 staging --env2 production -s "myapp/{env}"
`Options:
-
(required) - First environment
- --env2 (required) - Second environment
- -d, --config-dir - Config directory (default: ./config)
- -s, --secret - Secret name template with {env} placeholder (default: {packageName}/{env})
- -r, --region - AWS region (default: us-east-1)
- --sources - Comma-separated merge sources (default: default,env,secrets)
- -o, --output - Output format: text or json (default: text)Example output:
`
Comparing configs: staging vs production
Sources: default, env~ app.port: 3001 -> 8080
~ debug: true -> false
+ replicas: 3
Output symbols:
-
Added (only in env2)
- - Deleted (only in env1)
- ~ Updated (changed between environments)Exit codes:
-
0 - Configs are identical
- 1 - Configs have differences
- 2` - Error occurredContributions are welcome! Please feel free to submit a Pull Request.
Apache-2.0
Amit Tal