Function getAppConfig

Intro

The Parameters utility provides an AppConfigProvider that allows to retrieve configuration profiles from AWS AppConfig.

Getting started

This utility supports AWS SDK v3 for JavaScript only. This allows the utility to be modular, and you to install only the SDK packages you need and keep your bundle size small.

To use the provider, you must install the Parameters utility and the AWS SDK v3 for JavaScript for AppConfig:

npm install @aws-lambda-powertools/parameters @aws-sdk/client-appconfigdata
Copy

Basic usage

Example

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a configuration profile
  const encodedConfig = await getAppConfig('my-config', {
    application: 'my-app',
    environment: 'prod',
  });
  const config = new TextDecoder('utf-8').decode(encodedConfig);
};
Copy

Advanced usage

Caching

By default, the provider will cache parameters retrieved in-memory for 5 seconds. You can adjust how long values should be kept in cache by using the maxAge parameter.

Example

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a configuration profile and cache it for 10 seconds
  const encodedConfig = await getAppConfig('my-config', {
    application: 'my-app',
    environment: 'prod',
  });
  const config = new TextDecoder('utf-8').decode(encodedConfig);
};
Copy

If instead you'd like to always ensure you fetch the latest parameter from the store regardless if already available in cache, use the forceFetch parameter.

Example

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a config and always fetch the latest value
  const config = await getAppConfig('my-config', {
    application: 'my-app',
    environment: 'prod',
    forceFetch: true,
  });
  const config = new TextDecoder('utf-8').decode(encodedConfig);
};
Copy

Transformations

For configurations stored as freeform JSON, Freature Flag, you can use the transform argument for deserialization. This will return a JavaScript object instead of a string.

Example

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a JSON config or Feature Flag and parse it as JSON
  const config = await getAppConfig('my-config', {
    application: 'my-app',
    environment: 'prod',
    transform: 'json'
  });
};
Copy

For configurations that are instead stored as base64-encoded binary data, you can use the transform argument set to binary for decoding. This will return a decoded string.

Example

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a base64-encoded string and decode it
  const config = await getAppConfig('my-config', {
    application: 'my-app',
    environment: 'prod',
    transform: 'binary'
  });
};
Copy

Extra SDK options

When retrieving a configuration profile, you can pass extra options to the AWS SDK v3 for JavaScript client by using the sdkOptions parameter.

Example

import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';

export const handler = async (): Promise<void> => {
  // Retrieve a config and pass extra options to the AWS SDK v3 for JavaScript client
  const config = await getAppConfig('my-config', {
    application: 'my-app',
    environment: 'prod',
    sdkOptions: {
      RequiredMinimumPollIntervalInSeconds: 60,
    },
  });
  const config = new TextDecoder('utf-8').decode(encodedConfig);
};
Copy

This object accepts the same options as the AWS SDK v3 for JavaScript AppConfigData client.

Built-in provider class

For greater flexibility such as configuring the underlying SDK client used by built-in providers, you can use the AppConfigProvider class.

For more usage examples, see our documentation.

See

https://docs.powertools.aws.dev/lambda-typescript/latest/utilities/parameters/