@azure/app-configuration
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published

    App Configuration client library for JavaScript

    Azure App Configuration is a managed service that helps developers centralize their application and feature settings simply and securely.

    Use the client library for App Configuration to:

    • Create flexible key representations and mappings
    • Tag keys with labels
    • Replay settings from any point in time

    Key links:

    Getting started

    Install the package

    npm install @azure/app-configuration

    Currently supported environments

    See our support policy for more details.

    Prerequisites

    Create an App Configuration resource

    You can use the Azure Portal or the Azure CLI to create an Azure App Configuration resource.

    Example (Azure CLI):

    az appconfig create --name <app-configuration-resource-name> --resource-group <resource-group-name> --location eastus
    

    Authenticate the client

    AppConfigurationClient can authenticate using a service principal or using a connection string.

    Authenticating with a service principal

    Authentication via service principal is done by:

    • Creating a credential using the @azure/identity package.
    • Setting appropriate RBAC rules on your AppConfiguration resource. More information on App Configuration roles can be found here.

    Using DefaultAzureCredential

    const azureIdentity = require("@azure/identity");
    const appConfig = require("@azure/app-configuration");
    
    const credential = new azureIdentity.DefaultAzureCredential();
    const client = new appConfig.AppConfigurationClient(
      endpoint, // ex: <https://<your appconfig resource>.azconfig.io>
      credential
    );

    More information about @azure/identity can be found here

    Authenticating with a connection string

    To get the Primary connection string for an App Configuration resource you can use this Azure CLI command:

    az appconfig credential list -g <resource-group-name> -n <app-configuration-resource-name> --query "([?name=='Primary'].connectionString)[0]"
    

    And in code you can now create your App Configuration client with the connection string you got from the Azure CLI:

    const client = new AppConfigurationClient("<connection string>");

    Key concepts

    The AppConfigurationClient has some terminology changes from App Configuration in the portal.

    • Key/Value pairs are represented as ConfigurationSetting objects
    • Locking and unlocking a setting is represented in the isReadOnly field, which you can toggle using setReadOnly.

    The client follows a simple design methodology - ConfigurationSetting can be passed into any method that takes a ConfigurationSettingParam or ConfigurationSettingId.

    This means this pattern works:

    const setting = await client.getConfigurationSetting({
      key: "hello"
    });
    
    setting.value = "new value!";
    await client.setConfigurationSetting(setting);
    
    // fields unrelated to just identifying the setting are simply
    // ignored (for instance, the `value` field)
    await client.setReadOnly(setting, true);
    
    // delete just needs to identify the setting so other fields are
    // just ignored
    await client.deleteConfigurationSetting(setting);

    or, for example, re-getting a setting:

    let setting = await client.getConfigurationSetting({
      key: "hello"
    });
    
    // re-get the setting
    setting = await client.getConfigurationSetting(setting);

    Examples

    Create and get a setting

    const appConfig = require("@azure/app-configuration");
    
    const client = new appConfig.AppConfigurationClient(
      "<App Configuration connection string goes here>"
    );
    
    async function run() {
      const newSetting = await client.setConfigurationSetting({
        key: "testkey",
        value: "testvalue",
        // Labels allow you to create variants of a key tailored
        // for specific use-cases like supporting multiple environments.
        // https://docs.microsoft.com/azure/azure-app-configuration/concept-key-value#label-keys
        label: "optional-label"
      });
    
      let retrievedSetting = await client.getConfigurationSetting({
        key: "testkey",
        label: "optional-label"
      });
    
      console.log("Retrieved value:", retrievedSetting.value);
    }
    
    run().catch((err) => console.log("ERROR:", err));

    Next steps

    The following samples show you the various ways you can interact with App Configuration:

    More in-depth examples can be found in the samples folder on GitHub.

    Contributing

    If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

    This module's tests are a mixture of live and unit tests, which require you to have an Azure App Configuration instance. To execute the tests you'll need to run:

    1. rush update
    2. rush build -t @azure/app-configuration
    3. Create a .env file with these contents in the sdk\appconfiguration\app-configuration folder: APPCONFIG_CONNECTION_STRING=connection string for your App Configuration instance
    4. cd sdk\appconfiguration\app-configuration
    5. npm run test.

    View our tests folder for more details.

    Related projects

    Impressions

    Install

    npm i @azure/app-configuration

    DownloadsWeekly Downloads

    11,123

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    959 kB

    Total Files

    93

    Last publish

    Collaborators

    • azure-sdk