Quickstart: Create a JavaScript app with Azure App Configuration

Article
09/09/2024

In this quickstart, you use Azure App Configuration to centralize storage and management of application settings using the Azure App Configuration JavaScript provider client library.

App Configuration provider for JavaScript is built on top of the Azure SDK for JavaScript and is designed to be easier to use with richer features. It enables access to key-values in App Configuration as a Map object. It offers features like configuration composition from multiple labels, key prefix trimming, automatic resolution of Key Vault references, and many more. As an example, this tutorial shows how to use the JavaScript provider in a Node.js app.

Prerequisites

An Azure account with an active subscription. Create a trial subscription.
An App Configuration store. Create a store.
LTS versions of Node.js. For information about installing Node.js either directly on Windows or using the Windows Subsystem for Linux (WSL), see Get started with Node.js

Add key-values

Add the following key-values to the App Configuration store. For more information about how to add key-values to a store using the Azure portal or the CLI, go to Create a key-value.

Key	Value	Content type
message	Message from Azure App Configuration	Leave empty
app.greeting	Hello World	Leave empty
app.json	{"myKey":"myValue"}	application/json

Create a Node.js console app

In this tutorial, you create a Node.js console app and load data from your App Configuration store.

Create a new directory for the project named app-configuration-quickstart.
```
mkdir app-configuration-quickstart
```
Switch to the newly created app-configuration-quickstart directory.
```
cd app-configuration-quickstart
```
Install the Azure App Configuration provider by using the npm install command.
```
npm install @azure/app-configuration-provider
```

Connect to an App Configuration store

The following examples demonstrate how to retrieve configuration data from Azure App Configuration and utilize it in your application. By default, the key-values are loaded as a Map object, allowing you to access each key-value using its full key name. However, if your application uses configuration objects, you can use the constructConfigurationObject helper API that creates a configuration object based on the key-values loaded from Azure App Configuration.

Create a file named app.js in the app-configuration-quickstart directory and copy the code from each sample.

Sample 1: Load key-values with default selector

In this sample, you connect to Azure App Configuration using a connection string and load key-values without specifying advanced options. By default, it loads all key-values with no label.

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

async function run() {
    console.log("Sample 1: Load key-values with default selector");

    // Connect to Azure App Configuration using a connection string and load all key-values with null label.
    const settings = await load(connectionString);

    console.log("---Consume configuration as a Map---");
    // Find the key "message" and print its value.
    console.log('settings.get("message"):', settings.get("message"));           // settings.get("message"): Message from Azure App Configuration
    // Find the key "app.greeting" and print its value.
    console.log('settings.get("app.greeting"):', settings.get("app.greeting")); // settings.get("app.greeting"): Hello World
    // Find the key "app.json" whose value is an object.
    console.log('settings.get("app.json"):', settings.get("app.json"));         // settings.get("app.json"): { myKey: 'myValue' }

    console.log("---Consume configuration as an object---");
    // Construct configuration object from loaded key-values, by default "." is used to separate hierarchical keys.
    const config = settings.constructConfigurationObject();
    // Use dot-notation to access configuration
    console.log("config.message:", config.message);             // config.message: Message from Azure App Configuration
    console.log("config.app.greeting:", config.app.greeting);   // config.app.greeting: Hello World
    console.log("config.app.json:", config.app.json);           // config.app.json: { myKey: 'myValue' }
}

run().catch(console.error);

Sample 2: Load specific key-values using selectors

In this sample, you load a subset of key-values by specifying the selectors option. Only keys starting with "app." are loaded. Note that you can specify multiple selectors based on your needs, each with keyFilter and labelFilter properties.

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

async function run() {
    console.log("Sample 2: Load specific key-values using selectors");

    // Load a subset of keys starting with "app." prefix.
    const settings = await load(connectionString, {
        selectors: [{
            keyFilter: "app.*"
        }],
    });

    console.log("---Consume configuration as a Map---");
    // The key "message" is not loaded as it does not start with "app."
    console.log('settings.has("message"):', settings.has("message"));           // settings.has("message"): false
    // The key "app.greeting" is loaded
    console.log('settings.has("app.greeting"):', settings.has("app.greeting")); // settings.has("app.greeting"): true
    // The key "app.json" is loaded
    console.log('settings.has("app.json"):', settings.has("app.json"));         // settings.has("app.json"): true

    console.log("---Consume configuration as an object---");
    // Construct configuration object from loaded key-values
    const config = settings.constructConfigurationObject({ separator: "." });
    // Use dot-notation to access configuration
    console.log("config.message:", config.message);         // config.message: undefined
    console.log("config.app.greeting:", config.app.greeting);   // config.app.greeting: Hello World
    console.log("config.app.json:", config.app.json);           // config.app.json: { myKey: 'myValue' }
}

run().catch(console.error);

Sample 3: Load key-values and trim prefix from keys

In this sample, you load key-values with an option trimKeyPrefixes. After key-values are loaded, the prefix "app." is trimmed from all keys. This is useful when you want to load configurations that are specific to your application by filtering to a certain key prefix, but you don't want your code to carry the prefix every time it accesses the configuration.

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

async function run() {
    console.log("Sample 3: Load key-values and trim prefix from keys");

    // Load all key-values with no label, and trim "app." prefix from all keys.
    const settings = await load(connectionString, {
        selectors: [{
            keyFilter: "app.*"
        }],
        trimKeyPrefixes: ["app."]
    });

    console.log("---Consume configuration as a Map---");
    // The original key "app.greeting" is trimmed as "greeting".
    console.log('settings.get("greeting"):', settings.get("greeting")); // settings.get("greeting"): Hello World
    // The original key "app.json" is trimmed as "json".
    console.log('settings.get("json"):', settings.get("json"));         // settings.get("json"): { myKey: 'myValue' }

    console.log("---Consume configuration as an object---");
    // Construct configuration object from loaded key-values with trimmed keys.
    const config = settings.constructConfigurationObject();
    // Use dot-notation to access configuration
    console.log("config.greeting:", config.greeting);   // config.greeting: Hello World
    console.log("config.json:", config.json);           // config.json: { myKey: 'myValue' }
}

run().catch(console.error);

Run the application

Set an environment variable named AZURE_APPCONFIG_CONNECTION_STRING, and set it to the connection string of your App Configuration store. At the command line, run the following command:
To run the app locally using the Windows command prompt, run the following command and replace <app-configuration-store-connection-string> with the connection string of your app configuration store:
```
setx AZURE_APPCONFIG_CONNECTION_STRING "<app-configuration-store-connection-string>"
```
If you use Windows PowerShell, run the following command and replace <app-configuration-store-connection-string> with the connection string of your app configuration store:
```
$Env:AZURE_APPCONFIG_CONNECTION_STRING = "<app-configuration-store-connection-string>"
```
If you use macOS, run the following command and replace <app-configuration-store-connection-string> with the connection string of your app configuration store:
```
export AZURE_APPCONFIG_CONNECTION_STRING='<app-configuration-store-connection-string>'
```
If you use Linux, run the following command and replace <app-configuration-store-connection-string> with the connection string of your app configuration store:
```
export AZURE_APPCONFIG_CONNECTION_STRING='<app-configuration-store-connection-string>'
```
Print the value of the environment variable to validate that it's set properly with the following command.
Using the Windows command prompt, restart the command prompt to allow the change to take effect and run the following command:
```
echo %AZURE_APPCONFIG_CONNECTION_STRING%
```
If you use Windows PowerShell, run the following command:
```
$Env:AZURE_APPCONFIG_CONNECTION_STRING
```
If you use macOS, run the following command:
```
echo "$AZURE_APPCONFIG_CONNECTION_STRING"
```
If you use Linux, run the following command:
```
echo "$AZURE_APPCONFIG_CONNECTION_STRING"
```

After the environment variable is properly set, run the following command to run the app locally:

node app.js

You should see the following output for each sample:

Sample 1

Sample 1: Load key-values with default selector
---Consume configuration as a Map---
settings.get("message"): Message from Azure App Configuration
settings.get("app.greeting"): Hello World
settings.get("app.json"): { myKey: 'myValue' }
---Consume configuration as an object---
config.message: Message from Azure App Configuration
config.app.greeting: Hello World
config.app.json: { myKey: 'myValue' }

Sample 2

Sample 2: Load specific key-values using selectors
---Consume configuration as a Map---
settings.has("message"): false
settings.has("app.greeting"): true
settings.has("app.json"): true
---Consume configuration as an object---
config.message: undefined
config.app.greeting: Hello World
config.app.json: { myKey: 'myValue' }

Sample 3

Sample 3: Load key-values and trim prefix from keys
---Consume configuration as a Map---
settings.get("greeting"): Hello World
settings.get("json"): { myKey: 'myValue' }
---Consume configuration as an object---
config.greeting: Hello World
config.json: { myKey: 'myValue' }

Clean up resources

If you don't want to continue using the resources created in this article, delete the resource group you created here to avoid charges.

Important

Deleting a resource group is irreversible. The resource group and all the resources in it are permanently deleted. Ensure that you don't accidentally delete the wrong resource group or resources. If you created the resources for this article inside a resource group that contains other resources you want to keep, delete each resource individually from its respective pane instead of deleting the resource group.

Sign in to the Azure portal, and select Resource groups.
In the Filter by name box, enter the name of your resource group.
In the result list, select the resource group name to see an overview.
Select Delete resource group.
You're asked to confirm the deletion of the resource group. Enter the name of your resource group to confirm, and select Delete.

After a few moments, the resource group and all its resources are deleted.

Next steps

In this quickstart, you created a new App Configuration store and learned how to access key-values using the App Configuration JavaScript provider in a Node.js app. To learn how to configure your app to dynamically refresh configuration settings, continue to the next tutorial.

Enable dynamic configuration