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 (@aws-sdk/client-appconfigdata). This allows the utility to be modular, and you to install only the SDK packages you need and keep your bundle size small.

Basic usage

Example

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

const configProvider = new AppConfigProvider({
  application: 'my-app',
  environment: 'prod',
});

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);
};
Copy

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({
  application: 'my-app',
  environment: 'prod',
});

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

const configProvider = new AppConfigProvider({
  application: 'my-app',
  environment: 'prod',
});

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

const configProvider = new AppConfigProvider({
  application: 'my-app',
  environment: 'prod',
});

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

const configProvider = new AppConfigProvider({
  application: 'my-app',
  environment: 'prod',
});

export const handler = async (): Promise<void> => {
  // Retrieve a base64-encoded string and decode it
  const config = await configProvider.get('my-config', { 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 { AppConfigProvider } from '@aws-lambda-powertools/parameters/appconfig';

const configProvider = new AppConfigProvider({
  application: 'my-app',
  environment: 'prod',
});

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);
};
Copy

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({
  application: 'my-app',
  environment: 'prod',
  clientConfig: { region: 'eu-west-1' },
});
Copy

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({
  application: 'my-app',
  environment: 'prod',
  awsSdkV3Client: client,
});
Copy

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

For more usage examples, see our documentation.