compose-env-aws-ssm

AWS Systems Manager Parameter Store source adapter for compose-env.

Installation

npm install compose-env-aws-ssm @aws-sdk/client-ssm

compose-env must also be installed in your project.

Usage

import { defineConfig, source } from 'compose-env'
import { awsSSMSource } from 'compose-env-aws-ssm'

const config = await defineConfig(
  {
    DATABASE_URL: { type: 'url',    required: true, secret: true },
    PORT:         { type: 'port',   default: 3000 },
    API_KEY:      { type: 'string', required: true, secret: true },
  },
  {
    sources: [
      awsSSMSource('/myapp/prod/'),
      source.env(),
    ],
  },
)

Parameters stored in SSM under /myapp/prod/ are loaded automatically. The path prefix is stripped and / separators in nested paths are replaced with __:

| SSM parameter name | Resolved key | |--------------------------|------------------| | /myapp/prod/DATABASE_URL | DATABASE_URL | | /myapp/prod/db/port | DB__PORT |

Key Normalization

By default, keys are uppercased (uppercase: true). Disable this if your SSM parameter names are already exact env var names and you need case preserved:

awsSSMSource('/myapp/prod/', { uppercase: false })

Options

| Option | Type | Default | Description | |-------------|-----------|---------------------------------------|-----------------------------------------------------------------------------| | region | string | process.env.AWS_REGION or us-east-1 | AWS region to use. | | uppercase | boolean | true | Uppercase key names. Nested / separators become __ (double underscore). |

Authentication

Authentication is handled by the AWS SDK's default credential chain. The following are supported automatically:

• Environment variables — AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
• IAM roles — EC2 instance profiles, ECS task roles, Lambda execution roles
• AWS profiles — ~/.aws/credentials and AWS_PROFILE

All parameters are fetched with WithDecryption: true, so SecureString parameters are decrypted automatically if your IAM role has ssm:GetParametersByPath and kms:Decrypt permissions.

Required IAM Permissions

{
  "Effect": "Allow",
  "Action": ["ssm:GetParametersByPath"],
  "Resource": "arn:aws:ssm:REGION:ACCOUNT_ID:parameter/myapp/prod/*"
}

For SecureString parameters, also allow kms:Decrypt on the relevant KMS key.

Source Priority

Sources are resolved in the order they are listed. Place awsSSMSource before or after source.env() depending on which should take precedence:

// SSM overrides local .env files
sources: [source.env(), awsSSMSource('/myapp/prod/')]

// Local .env files override SSM (useful for local development)
sources: [awsSSMSource('/myapp/prod/'), source.env()]