env-ssm

Load environment from SSM Parameter Store.

Install

This package has a peer dependency to env-var and @aws-sdk/client-ssm. To install, use the following command:

npm install @byu-oit/env-ssm @aws-sdk/client-ssm env-var

If specifying a tfvars file, please install @byu-oit/dottfvars: npm install @byu-oit/dottfvars

If specifying a dotenv file, please install dotenv: npm install dotenv

For convenience installing them all: npm install @byu-oit/env @aws-sdk/client-ssm env-var @byu-oit/dottfvars dotenv

Options

| Option | Type | Description | Default | |:--------------|:--------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------| | ssm | SSMClient | An AWS SSM client instance. The default SSM client can be configured with environment variables or a custom instance may be provided. | SSMClient | | paths | PathSsmLike OR PathSsmLike[] | The SSM parameter store path to use. All parameters that fall under this path will be returned as properties in the environment variables object. Parameters with multiple nested children will be returned as stringified JSON. | [] | | pathDelimiter | string | Specify a path delimiter. | / | | processEnv | boolean | If true, it will add process.env variables to the container. | true | | tfvars | string | Adds local tfvars variables to the environment. Must be the exact path to the tfvars file relative to the project or package root. | false | | dotenv | boolean OR string | Adds local .env variables to the environment. Can be false, which disables .env support. May also be the exact path to the .env file relative to the project or package root. | process.cwd() + '/.env' |

ProTip: Use environment variables to the following options:

• ENV_SSM_PATHS
• ENV_SSM_PATH_DELIMITER
• ENV_SSM_PROCESS_ENV
• ENV_SSM_TFVARS
• ENV_SSM_DOTENV

NOTE: All the options are cast from string to the type listed in the table above. When using ENV_SSM_PATHS, a comma-delimited list of paths (e.g. /app/dev,/app/prd) or JSON object or array of PathSsmLike may be supplied.

Usage

Variables load (and are overwritten if duplicates are found) in the following order:

1. Load SSM
2. Load .env file
3. Load .tfvars file
4. Load process.env

Single Path

SSM Path: /my/app SSM Parameters:

• /my/app/db/user => admin
• /my/app/db/pass => ch@ng3m3
• /my/app/host => example.com

import EnvSsm from 'env-ssm'

/**
 * @returns {db: {user: 'admin', pass: 'ch@ng3m3'}, host: 'example.com'}
 */
async function getParams () {
  const env = await EnvSsm(path)
  const db = env.get('db').required().asJsonObject()
  const host = env.get('api').required().asString()
  return { db, host }
}

Multiple Paths & Delimiters

SSM Paths:

• /my/app
• my.app

SSM Parameters:

• /my/app/db/user => admin
• /my/app/db/pass => ch@ng3m3
• my.app.host => example.com

import EnvSsm from 'env-ssm'

/**
 * @returns {db: {user: 'admin', pass: 'ch@ng3m3'}, host: 'example.com'}
 */
async function getParams () {
  const env = await EnvSsm([
    '/my/app',

    // If no delimiter is specified, the path is treated as a single property name
    { path: 'my.app', delimiter: '.' }
  ])
  const db = env.get('db').required().asJsonObject()
  const host = env.get('api').required().asString()
  return { db, host }
}

For Local Development

For the given tfvars, .env, and ssm path:

SSM Path: /my/app SSM Parameters:

• /my/app/db/user => admin

# local.tfvars file located in current working directory
db = {
  user = 'user'
  pass = 'ch@ng3m3'
}
host = 'JohnDoe.com'

# .env file located in current working directory
host='example.com'

/**
 * @returns {db: {user: 'user', pass: 'ch@ng3m3'}, host: 'JohnDoe.com'}
 */
async function getParams () {
  const env = await EnvSsm({
    // Allows multiple paths
    paths: [path],

    // Specify file name relative to process.cwd()
    tfvars: 'local.tfvars',

    // By default, checks process.cwd() + '/.env' or else specify a file name relative to process.cwd()
    // dotenv: .env
  })
  const db = env.get('db').required().asJsonObject()
  const host = env.get('api').required().asString()
  return { db, host }
}