Azure App Configuration SDK for JavaScript

This documentation provides comprehensive guidance on using the Azure App Configuration client library for JavaScript. This SDK allows you to interact with Azure App Configuration services, enabling centralized management of application settings and feature flags.

Note: This documentation is for version 7.x.x of the Azure App Configuration SDK. For older versions, please refer to the archive.

Getting Started

To begin using the Azure App Configuration SDK, you first need to install it:

npm install @azure/app-configuration

Once installed, you can create an instance of the AppConfigurationClient and start interacting with your App Configuration store.

Prerequisites

An Azure subscription.
An Azure App Configuration store.
An Azure Active Directory (Azure AD) tenant (if using Azure AD authentication).

Authentication

The SDK supports several authentication methods, including connection string, Azure AD, and Managed Identity. The recommended approach is to use Azure Identity.

Using Connection String


const { AppConfigurationClient } = require("@azure/app-configuration");

const connectionString = "endpoint=https://your-appconfig-name.azconfig.io;id=your_id;secret=your_secret";
const client = new AppConfigurationClient(connectionString);

Using Azure Identity (Recommended)

For Azure AD authentication, you can leverage the @azure/identity package.


const { AppConfigurationClient } = require("@azure/app-configuration");
const { DefaultAzureCredential } = require("@azure/identity");

const endpoint = "https://your-appconfig-name.azconfig.io";
const credential = new DefaultAzureCredential();
const client = new AppConfigurationClient(endpoint, credential);

Ensure your Azure AD principal has appropriate roles (e.g., 'App Configuration Data Reader') assigned to your App Configuration store.

Core Concepts

Azure App Configuration allows you to manage configuration data in a hierarchical and organized manner. Key concepts include:

Key-Value Pairs: The fundamental unit of configuration data. Keys are unique identifiers, and values store the configuration settings.
Labels: A mechanism to group configuration settings, often used for different environments (e.g., "development", "staging", "production") or application versions.
Feature Flags: A powerful feature to enable or disable application features dynamically without redeploying code.
Configuration Snapshots: A point-in-time capture of your configuration data, useful for auditing and rollbacks.

Common Operations

Managing Key-Value Pairs

You can add, retrieve, update, and delete key-value pairs.

Retrieving a Key-Value Pair


async function getKey(keyName, labelName = null) {
    try {
        const result = await client.getConfigurationSetting(keyName, labelName);
        console.log(`Key: ${result.key}, Value: ${result.value}, Label: ${result.label}`);
        return result;
    } catch (error) {
        console.error("Error retrieving key-value pair:", error);
        throw error;
    }
}

// Example usage:
// getKey(".appsettings:MySetting", "production");

Adding a Key-Value Pair


async function addKeyValue(keyName, value, labelName = null) {
    try {
        const result = await client.addConfigurationSetting({
            key: keyName,
            value: value,
            label: labelName
        });
        console.log(`Added key: ${result.key}, Value: ${result.value}, Label: ${result.label}`);
        return result;
    } catch (error) {
        console.error("Error adding key-value pair:", error);
        throw error;
    }
}

// Example usage:
// addKeyValue(".appsettings:NewSetting", "new_value", "development");

Updating a Key-Value Pair


async function updateKeyValue(keyName, value, labelName = null) {
    try {
        const result = await client.setConfigurationSetting({
            key: keyName,
            value: value,
            label: labelName
        });
        console.log(`Updated key: ${result.key}, Value: ${result.value}, Label: ${result.label}`);
        return result;
    } catch (error) {
        console.error("Error updating key-value pair:", error);
        throw error;
    }
}

// Example usage:
// updateKeyValue(".appsettings:MySetting", "updated_value", "production");

Deleting a Key-Value Pair


async function deleteKeyValue(keyName, labelName = null) {
    try {
        await client.deleteConfigurationSetting(keyName, labelName);
        console.log(`Deleted key: ${keyName}, Label: ${labelName || "default"}`);
    } catch (error) {
        console.error("Error deleting key-value pair:", error);
        throw error;
    }
}

// Example usage:
// deleteKeyValue(".appsettings:NewSetting", "development");

Managing Feature Flags

Control application behavior by enabling or disabling features dynamically.

Retrieving a Feature Flag


async function getFeatureFlag(name, labelName = null) {
    try {
        const result = await client.getConfigurationSetting(`.${name}`, labelName, "Microsoft.AppConfiguration.FeatureFlag/enabled");
        console.log(`Feature flag '${name}' (Label: ${result.label}) is: ${result.value}`);
        return result;
    } catch (error) {
        console.error("Error retrieving feature flag:", error);
        throw error;
    }
}

// Example usage:
// getFeatureFlag("BetaFeature");

Enabling a Feature Flag


async function enableFeatureFlag(name, labelName = null) {
    try {
        const result = await client.setConfigurationSetting({
            key: `.${name}`,
            value: "true",
            label: labelName,
            contentType: "application/vnd.microsoft.appconfig.ff+json;charset=utf-8",
            tags: {
                "key": name
            }
        });
        console.log(`Feature flag '${name}' (Label: ${result.label}) enabled.`);
        return result;
    } catch (error) {
        console.error("Error enabling feature flag:", error);
        throw error;
    }
}

// Example usage:
// enableFeatureFlag("BetaFeature", "development");

Querying and Filtering

List key-value pairs and feature flags based on various criteria.

Listing all Key-Value Pairs


async function listAllKeys() {
    const settings = [];
    for await (const setting of client.listConfigurationSettings()) {
        settings.push(setting);
        console.log(`Key: ${setting.key}, Value: ${setting.value}, Label: ${setting.label}`);
    }
    return settings;
}

// Example usage:
// listAllKeys();

Listing Key-Value Pairs with a Label


async function listKeysByLabel(labelName) {
    const settings = [];
    for await (const setting of client.listConfigurationSettings({ labelFilter: labelName })) {
        settings.push(setting);
        console.log(`Key: ${setting.key}, Value: ${setting.value}, Label: ${setting.label}`);
    }
    return settings;
}

// Example usage:
// listKeysByLabel("staging");

Listing Feature Flags


async function listFeatureFlags() {
    const flags = [];
    for await (const setting of client.listConfigurationSettings({
        keyFilter: ".?*" // Filter for keys starting with '.'
    })) {
        // Additional filtering might be needed to confirm it's a feature flag if not using contentType
        if (setting.contentType === "application/vnd.microsoft.appconfig.ff+json;charset=utf-8") {
            flags.push(setting);
            console.log(`Feature Flag: ${setting.key.substring(1)}, Label: ${setting.label}`);
        }
    }
    return flags;
}

// Example usage:
// listFeatureFlags();

Advanced Topics

Examples

Explore practical examples demonstrating common use cases:

Code Samples

For a comprehensive collection of code examples, please visit the Azure SDK for JS samples repository on GitHub.

Best Practices

Always use environment variables or Azure Key Vault to manage your App Configuration connection string or credentials in production environments.