@dyanet/config-aws

Framework-agnostic AWS configuration management library for Node.js applications.

Features

• Multiple Configuration Sources: Load configuration from environment variables, .env files, AWS Secrets Manager, AWS SSM Parameter Store, and S3
• Configurable Precedence: Control which sources override others with aws-first, local-first, or custom precedence strategies
• AWS ECS Compatible: .env file parsing follows the AWS ECS environment file format
• Zod Validation: Optional schema validation using Zod
• Framework Agnostic: Works with any JavaScript/TypeScript application
• Tree-Shakeable: ESM and CommonJS builds with full tree-shaking support

Installation

npm install @dyanet/config-aws

Peer Dependencies

Install the AWS SDK clients you need:

# For Secrets Manager
npm install @aws-sdk/client-secrets-manager

# For SSM Parameter Store
npm install @aws-sdk/client-ssm

# For S3
npm install @aws-sdk/client-s3

# For schema validation
npm install zod

Quick Start

import { ConfigManager, EnvironmentLoader, SecretsManagerLoader } from '@dyanet/config-aws';
import { z } from 'zod';

// Define your configuration schema
const configSchema = z.object({
  DATABASE_URL: z.string(),
  API_KEY: z.string(),
  PORT: z.string().transform(Number),
});

// Create and load configuration
const configManager = new ConfigManager({
  loaders: [
    new EnvironmentLoader({ prefix: 'APP_' }),
    new SecretsManagerLoader({ secretName: '/myapp/config' }),
  ],
  schema: configSchema,
  precedence: 'aws-first', // AWS values override local
});

await configManager.load();

// Access configuration
const dbUrl = configManager.get('DATABASE_URL');
const allConfig = configManager.getAll();

Loaders

EnvironmentLoader

Loads configuration from process.env with optional prefix filtering.

new EnvironmentLoader({
  prefix: 'APP_',        // Only load vars starting with APP_
  exclude: ['APP_DEBUG'] // Exclude specific variables
});

EnvFileLoader

Loads configuration from .env files using AWS ECS format.

new EnvFileLoader({
  paths: ['.env', '.env.local'], // Files to load (later overrides earlier)
  override: true                  // Whether later files override earlier
});

S3Loader

Loads configuration from S3 buckets (JSON or .env format).

new S3Loader({
  bucket: 'my-config-bucket',
  key: 'config/production.json',
  format: 'auto' // 'json', 'env', or 'auto'
});

SecretsManagerLoader

Loads configuration from AWS Secrets Manager.

new SecretsManagerLoader({
  secretName: '/myapp/secrets',
  region: 'us-east-1',
  environmentMapping: {
    local: 'dev',
    development: 'dev',
    production: 'prod'
  }
});

SSMParameterStoreLoader

Loads configuration from AWS SSM Parameter Store.

new SSMParameterStoreLoader({
  parameterPath: '/myapp/config',
  region: 'us-east-1',
  withDecryption: true
});

Precedence Strategies

• aws-first: Local sources load first, AWS sources override (AWS wins)
• local-first: AWS sources load first, local sources override (local wins)
• Custom: Define your own order with LoaderPrecedence[]

// Custom precedence (higher priority = later, overrides earlier)
const configManager = new ConfigManager({
  loaders: [envLoader, secretsLoader, ssmLoader],
  precedence: [
    { loader: 'EnvironmentLoader', priority: 1 },
    { loader: 'SecretsManagerLoader', priority: 2 },
    { loader: 'SSMParameterStoreLoader', priority: 3 }, // Highest priority wins
  ]
});

Verbose Logging

Enable detailed logging to debug configuration loading:

const configManager = new ConfigManager({
  loaders: [...],
  verbose: {
    logKeys: true,      // Log variable names
    logOverrides: true, // Log when values are overridden
    logTiming: true,    // Log loader timing
    logValues: false,   // Don't log values (security)
  }
});

Error Handling

The library provides specific error classes:

• ConfigurationError - Base error class
• ValidationError - Zod schema validation failed
• AWSServiceError - AWS API call failed
• ConfigurationLoadError - Loader failed to load
• MissingConfigurationError - Required keys missing

try {
  await configManager.load();
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid config:', error.validationErrors);
  } else if (error instanceof AWSServiceError) {
    console.error(`AWS ${error.service} failed:`, error.message);
  }
}

Framework Adapters

• NestJS: Use @dyanet/nestjs-config-aws for NestJS integration
• Next.js: Use @dyanet/nextjs-config-aws for Next.js integration

License

MIT