|
| 1 | +--- |
| 2 | +title: JavaScript Configuration Provider |
| 3 | +titleSuffix: Azure App Configuration |
| 4 | +description: Learn to load configurations and feature flags from the Azure App Configuration service in JavaScript. |
| 5 | +services: azure-app-configuration |
| 6 | +author: zhiyuanliang-ms |
| 7 | +ms.author: zhiyuanliang |
| 8 | +ms.service: azure-app-configuration |
| 9 | +ms.devlang: javascript |
| 10 | +ms.custom: devx-track-javascript |
| 11 | +ms.topic: tutorial |
| 12 | +ms.date: 02/02/2025 |
| 13 | +#Customer intent: I want to learn how to use Azure App Configuration JavaScript client library. |
| 14 | +--- |
| 15 | + |
| 16 | +# JavaScript Configuration Provider |
| 17 | + |
| 18 | +[](https://www.npmjs.com/package/@azure/app-configuration-provider) |
| 19 | + |
| 20 | +Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely. The JavaScript configuration provider library enables loading configuration from an Azure App Configuration store in a managed way. This client library adds additional functionality above the Azure SDK for JavaScript. |
| 21 | + |
| 22 | +## Load configuration |
| 23 | + |
| 24 | +The `load` method exported in the `@azure/app-configuration-provider` package is used to load configuration from the Azure App Configuration. The `load` method allows you to either use Microsoft Entra ID or connection string to connect to the App Configuration store. |
| 25 | + |
| 26 | +### [Microsoft Entra ID](#tab/entra-id) |
| 27 | + |
| 28 | +You use the `DefaultAzureCredential` to authenticate to your App Configuration store. Follow the [instructions](./concept-enable-rbac.md#authentication-with-token-credentials) to assign your credential the **App Configuration Data Reader** role. |
| 29 | + |
| 30 | +```javascript |
| 31 | +const { load } = require("@azure/app-configuration-provider"); |
| 32 | +const { DefaultAzureCredential } = require("@azure/identity"); |
| 33 | +const endpoint = process.env.AZURE_APPCONFIG_ENDPOINT; |
| 34 | +const credential = new DefaultAzureCredential(); // For more information, see https://learn.microsoft.com/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility |
| 35 | + |
| 36 | +async function run() { |
| 37 | + // Connect to Azure App Configuration using a token credential and load all key-values with no label. |
| 38 | + const settings = await load(endpoint, credential); |
| 39 | + console.log('settings.get("message"):', settings.get("message")); |
| 40 | +} |
| 41 | + |
| 42 | +run(); |
| 43 | +``` |
| 44 | + |
| 45 | +### [Connection string](#tab/connection-string) |
| 46 | + |
| 47 | +```javascript |
| 48 | +const { load } = require("@azure/app-configuration-provider"); |
| 49 | +const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING; |
| 50 | + |
| 51 | +async function run() { |
| 52 | + // Connect to Azure App Configuration using a connection string and load all key-values with no label. |
| 53 | + const settings = await load(connectionString); |
| 54 | + console.log('settings.get("message"):', settings.get("message")); |
| 55 | +} |
| 56 | + |
| 57 | +run(); |
| 58 | +``` |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +The `load` method returns an instance of `AzureAppConfiguration` type which is defined as follows: |
| 63 | + |
| 64 | +```typescript |
| 65 | +type AzureAppConfiguration = { |
| 66 | + refresh(): Promise<void>; |
| 67 | + onRefresh(listener: () => any, thisArg?: any): Disposable; |
| 68 | +} & IGettable & ReadonlyMap<string, any> & IConfigurationObject; |
| 69 | +``` |
| 70 | + |
| 71 | +For more information about `refresh` and `onRefresh` methods, see the [Configuration refresh](#configuration-refresh) section. |
| 72 | + |
| 73 | +### Consume configuration |
| 74 | + |
| 75 | +The `AzureAppConfiguration` type extends the following interfaces: |
| 76 | + |
| 77 | +- `IGettable` |
| 78 | + |
| 79 | + ```typescript |
| 80 | + interface IGettable { |
| 81 | + get<T>(key: string): T | undefined; |
| 82 | + } |
| 83 | + ``` |
| 84 | + |
| 85 | + The `IGettable` interface provides `get` method to retrieve the value of a key-value from the Map-styled data structure. |
| 86 | + |
| 87 | + ```typescript |
| 88 | + const settings = await load(endpoint, credential); |
| 89 | + const fontSize = settings.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store |
| 90 | + ``` |
| 91 | + |
| 92 | +- `ReadonlyMap` |
| 93 | + |
| 94 | + The `AzureAppConfiguration` type also extends the [`ReadonlyMap`](https://typestrong.org/typedoc-auto-docs/typedoc/interfaces/TypeScript.ReadonlyMap.html) interface, providing read-only access to key-value pairs. |
| 95 | + |
| 96 | +- `IConfigurationObject` |
| 97 | + |
| 98 | + ```typescript |
| 99 | + interface IConfigurationObject { |
| 100 | + constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>; |
| 101 | + } |
| 102 | + ``` |
| 103 | + |
| 104 | + The `IConfigurationObject` interface provides `constructConfigurationObject` method to construct a configuration object based on a Map-styled data structure and hierarchical keys. The optional `ConfigurationObjectConstructionOptions` parameter can be used to specify the separator for converting hierarchical keys to object properties. By default, the separator is `"."`. |
| 105 | + |
| 106 | + ```typescript |
| 107 | + interface ConfigurationObjectConstructionOptions { |
| 108 | + separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators |
| 109 | + } |
| 110 | + ``` |
| 111 | + |
| 112 | + In JavaScript, objects or maps are commonly used as the primary data structures to represent configurations. The JavaScript configuration provider library supports both of the configuration approaches, providing developers with the flexibility to choose the option that best fits their needs. |
| 113 | + |
| 114 | + ```typescript |
| 115 | + const settings = await load(endpoint, credential); |
| 116 | + const settingsObj = settings.constructConfigurationObject({separator: ":"}); |
| 117 | + const fontSize1 = settings.get("app:font:size"); // map-style configuration representation |
| 118 | + const fontSize2 = settingsObj.app.font.size; // object-style configuration representation |
| 119 | + ``` |
| 120 | + |
| 121 | +### Load specific key-values using selectors |
| 122 | + |
| 123 | +By default, the `load` method will load all configurations with no label from the configuration store. You can configure the behavior of the `load` method through the optional parameter of [`AzureAppConfigurationOptions`](https://github.com/Azure/AppConfiguration-JavaScriptProvider/blob/main/src/AzureAppConfigurationOptions.ts) type. |
| 124 | + |
| 125 | +To refine or expand the configurations loaded from the App Configuration store, you can specify the key or label selectors under the `AzureAppConfigurationOptions.selectors` property. |
| 126 | + |
| 127 | +```typescript |
| 128 | +const settings = await load(endpoint, credential, { |
| 129 | + selectors: [ |
| 130 | + { // load the subset of keys starting with "app1." prefix and "test" label |
| 131 | + keyFilter: "app1.*", |
| 132 | + labelFilter: "test" |
| 133 | + }, |
| 134 | + { // load the subset of keys starting with "dev" label" |
| 135 | + labelFilter: "dev*" |
| 136 | + } |
| 137 | + ] |
| 138 | +}); |
| 139 | +``` |
| 140 | + |
| 141 | +> [!NOTE] |
| 142 | +> Key-values are loaded in the order in which the selectors are listed. If multiple selectors retrieve key-values with the same key, the value from the last one will override any previously loaded value. |
| 143 | + |
| 144 | +### Trim prefix from keys |
| 145 | + |
| 146 | +You can trim the prefix off of keys by providing a list of trimmed key prefixes to the `AzureAppConfigurationOptions.trimKeyPrefixes` property. |
| 147 | + |
| 148 | +```typescript |
| 149 | +const settings = await load(endpoint, credential, { |
| 150 | + selectors: [{ |
| 151 | + keyFilter: "app.*" |
| 152 | + }], |
| 153 | + trimKeyPrefixes: ["app."] |
| 154 | +}); |
| 155 | +``` |
| 156 | + |
| 157 | +## Key Vault reference |
| 158 | + |
| 159 | +Azure App Configuration supports referencing secrets stored in Azure Key Vault. In App Configuration, you can create keys that map to secrets stored in Key Vault. The secrets are securely stored in Key Vault, but can be accessed like any other configuration once loaded. |
| 160 | + |
| 161 | +The configuration provider library retrieves Key Vault references, just as it does for any other keys stored in App Configuration. Because the client recognizes the keys as Key Vault references, they have a unique content-type, and the client will connect to Key Vault to retrieve their values for your application. You need to configure `AzureAppConfigurationOptions.KeyVaultOptions` property with the proper credential to allow the configuration provider to connect to Azure Key Vault. |
| 162 | + |
| 163 | +```typescript |
| 164 | +const credential = new DefaultAzureCredential(); |
| 165 | +const settings = await load(endpoint, credential, { |
| 166 | + keyVaultOptions: { |
| 167 | + credential: credential |
| 168 | + } |
| 169 | +}); |
| 170 | +``` |
| 171 | + |
| 172 | +You can also provide `SecretClient` instance directly to `KeyVaultOptions`. In this way, you can customize the options while creating `SecretClient`. |
| 173 | + |
| 174 | +```typescript |
| 175 | +const { SecretClient } = require("@azure/keyvault-secrets"); |
| 176 | +
|
| 177 | +const credential = new DefaultAzureCredential(); |
| 178 | +const secretClient = new SecretClient(keyVaultUrl, credential, { |
| 179 | + serviceVersion: "7.0", |
| 180 | +}); |
| 181 | +const settings = await load(endpoint, credential, { |
| 182 | + keyVaultOptions: { |
| 183 | + secretClients: [ secretClient ] |
| 184 | + } |
| 185 | +}); |
| 186 | +``` |
| 187 | + |
| 188 | +You can also set `secretResolver` property to locally resolve secrets that don’t have a Key Vault associated with them. |
| 189 | + |
| 190 | +```typescript |
| 191 | +const resolveSecret = (url) => "From Secret Resolver"; |
| 192 | +const settings = await load(endpoint, credential, { |
| 193 | + keyVaultOptions: { |
| 194 | + secretResolver: resolveSecret |
| 195 | + } |
| 196 | +}); |
| 197 | +``` |
| 198 | + |
| 199 | +## Configuration refresh |
| 200 | + |
| 201 | +Dynamic refresh for the configurations lets you pull their latest values from the App Configuration store without having to restart the application. You can set `AzureAppConfigurationOptions.refreshOptions` to enable the refresh and configure refresh options. The loaded configuration will be updated when any change of selected key-values is detected on the server. By default, a refresh interval of 30 seconds is used, but you can override it with the `refreshIntervalInMs` property. |
| 202 | + |
| 203 | +```typescript |
| 204 | +const settings = await load(endpoint, credential, { |
| 205 | + refreshOptions: { |
| 206 | + enabled: true, |
| 207 | + refreshIntervalInMs: 15_000 |
| 208 | + } |
| 209 | +}); |
| 210 | +``` |
| 211 | + |
| 212 | +Setting up `refreshOptions` alone won't automatically refresh the configuration. You need to call the `refresh` method on `AzureAppConfiguration` instance returned by the `load` method to trigger a refresh. |
| 213 | + |
| 214 | +``` typescript |
| 215 | +// this call is not blocking, the configuration will be updated asynchronously |
| 216 | +settings.refresh(); |
| 217 | +``` |
| 218 | + |
| 219 | +This design prevents unnecessary requests to App Configuration when your application is idle. You should include the `refresh` call where your application activity occurs. This is known as **activity-driven configuration refresh**. For example, you can call `refresh` when processing an incoming request or inside an iteration where you perform a complex task. |
| 220 | + |
| 221 | +```typescript |
| 222 | +const server = express(); |
| 223 | +// Use an express middleware to refresh configuration whenever a request comes in |
| 224 | +server.use((req, res, next) => { |
| 225 | + settings.refresh(); |
| 226 | + next(); |
| 227 | +}) |
| 228 | +``` |
| 229 | + |
| 230 | +Even if the refresh call fails for any reason, your application will continue to use the cached configuration. Another attempt will be made when the configured refresh interval has passed and the refresh call is triggered by your application activity. Calling `refresh` is a no-op before the configured refresh interval elapses, so its performance impact is minimal even if it's called frequently. |
| 231 | + |
| 232 | +For more information about refresh configuration, go to [Use dynamic configuration in JavaScript](./enable-dynamic-configuration-javascript.md). |
| 233 | + |
| 234 | +## Feature flag |
| 235 | + |
| 236 | +You can [create feature flags](./manage-feature-flags.md#create-a-feature-flag) in Azure App Configuration. By default, the feature flags will not be loaded by configuration provider. You can enable loading and refreshing feature flags through `AzureAppConfigurationOptions.featureFlagOptions` property when calling the `load` method. |
| 237 | + |
| 238 | +```typescript |
| 239 | +const settings = await load(endpoint, credential, { |
| 240 | + featureFlagOptions: { |
| 241 | + enabled: true, |
| 242 | + selectors: [ { keyFilter: "*", labelFilter: "Prod" } ], |
| 243 | + refresh: { |
| 244 | + enabled: true, |
| 245 | + refreshIntervalInMs: 10_000 |
| 246 | + } |
| 247 | + } |
| 248 | +}); |
| 249 | +``` |
| 250 | + |
| 251 | +> [!NOTE] |
| 252 | +> If `featureFlagOptions` is enabled and no selector is specified, the configuration provider will load all feature flags with no label from the App Configuration store. |
| 253 | + |
| 254 | +### Feature management |
| 255 | + |
| 256 | +Feature management library provides a way to develop and expose application functionality based on feature flags. The feature management library is designed to work in conjunction with the configuration provider library. The configuration provider will load all selected feature flags into the configuration under the `feature_flags` list of the `feature_management` section. The feature management library will consume and manage the loaded feature flags for your application. |
| 257 | + |
| 258 | +For more information about how to use the JavaScript feature management library, go to the [feature flag quickstart](./quickstart-feature-flag-javascript.md). |
| 259 | + |
| 260 | +## Geo-replication |
| 261 | + |
| 262 | +For information about using geo-replication, go to [Enable geo-replication](./howto-geo-replication.md). |
| 263 | + |
| 264 | +## Next steps |
| 265 | + |
| 266 | +To learn how to use the JavaScript configuration provider, continue to the following tutorial. |
| 267 | + |
| 268 | +> [!div class="nextstepaction"] |
| 269 | +> [Use dynamic configuration in JavaScript](./enable-dynamic-configuration-javascript.md) |
0 commit comments