Class AppConfigProvider

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

Basic usage

Example

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

const configProvider = new AppConfigProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a configuration profile
  const encodedConfig = await configProvider.get('my-config');
  const config = new TextDecoder('utf-8').decode(encodedConfig);
};

If you want to retrieve configs without customizing the provider, you can use the getAppConfig function instead.

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 { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';

const configProvider = new AppConfigProvider();

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

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 { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';

const configProvider = new AppConfigProvider();

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

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 { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';

const configProvider = new AppConfigProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a JSON config or Feature Flag and parse it as JSON
  const config = await configProvider.get('my-config', { transform: 'json' });
};

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 { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';

const configProvider = new AppConfigProvider();

export const handler = async (): Promise<void> => {
  // Retrieve a base64-encoded string and decode it
  const config = await configProvider.get('my-config', { transform: 'binary' });
};

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 { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';

const configProvider = new AppConfigProvider();

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

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

Customize AWS SDK v3 for JavaScript client

By default, the provider will create a new AppConfigData client using the default configuration.

You can customize the client by passing a custom configuration object to the provider.

Example

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

const configProvider = new AppConfigProvider({
  clientConfig: { region: 'eu-west-1' },
});

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

Otherwise, if you want to use a custom client altogether, you can pass it to the provider.

Example

import { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';
import { AppConfigDataClient } from '@aws-sdk/client-appconfigdata';

const client = new AppConfigDataClient({ region: 'eu-west-1' });
const configProvider = new AppConfigProvider({
  awsSdkV3Client: client,
});

This object must be an instance of the AWS SDK v3 for JavaScript AppConfig Data client.

For more usage examples, see our documentation.