Azure Appconfiguration Ts

1---
2name: azure-appconfiguration-ts
3description: Build applications using Azure App Configuration SDK for JavaScript (@azure/app-configuration). Use when working with configuration settings, feature flags, Key Vault references, dynamic refresh, or centralized configuration management.
4package: "@azure/app-configuration"
5---
6 
7# Azure App Configuration SDK for TypeScript
8 
9Centralized configuration management with feature flags and dynamic refresh.
10 
11## Installation
12 
13```bash
14# Low-level CRUD SDK
15npm install @azure/app-configuration @azure/identity
16 
17# High-level provider (recommended for apps)
18npm install @azure/app-configuration-provider @azure/identity
19 
20# Feature flag management
21npm install @microsoft/feature-management
22```
23 
24## Environment Variables
25 
26```bash
27AZURE_APPCONFIG_ENDPOINT=https://<your-resource>.azconfig.io
28# OR
29AZURE_APPCONFIG_CONNECTION_STRING=Endpoint=https://...;Id=...;Secret=...
30```
31 
32## Authentication
33 
34```typescript
35import { AppConfigurationClient } from "@azure/app-configuration";
36import { DefaultAzureCredential } from "@azure/identity";
37 
38// DefaultAzureCredential (recommended)
39const client = new AppConfigurationClient(
40  process.env.AZURE_APPCONFIG_ENDPOINT!,
41  new DefaultAzureCredential()
42);
43 
44// Connection string
45const client2 = new AppConfigurationClient(
46  process.env.AZURE_APPCONFIG_CONNECTION_STRING!
47);
48```
49 
50## CRUD Operations
51 
52### Create/Update Settings
53 
54```typescript
55// Add new (fails if exists)
56await client.addConfigurationSetting({
57  key: "app:settings:message",
58  value: "Hello World",
59  label: "production",
60  contentType: "text/plain",
61  tags: { environment: "prod" },
62});
63 
64// Set (create or update)
65await client.setConfigurationSetting({
66  key: "app:settings:message",
67  value: "Updated value",
68  label: "production",
69});
70 
71// Update with optimistic concurrency
72const existing = await client.getConfigurationSetting({ key: "myKey" });
73existing.value = "new value";
74await client.setConfigurationSetting(existing, { onlyIfUnchanged: true });
75```
76 
77### Read Settings
78 
79```typescript
80// Get single setting
81const setting = await client.getConfigurationSetting({
82  key: "app:settings:message",
83  label: "production",  // optional
84});
85console.log(setting.value);
86 
87// List with filters
88const settings = client.listConfigurationSettings({
89  keyFilter: "app:*",
90  labelFilter: "production",
91});
92 
93for await (const setting of settings) {
94  console.log(`${setting.key}: ${setting.value}`);
95}
96```
97 
98### Delete Settings
99 
100```typescript
101await client.deleteConfigurationSetting({
102  key: "app:settings:message",
103  label: "production",
104});
105```
106 
107### Lock/Unlock (Read-Only)
108 
109```typescript
110// Lock
111await client.setReadOnly({ key: "myKey", label: "prod" }, true);
112 
113// Unlock
114await client.setReadOnly({ key: "myKey", label: "prod" }, false);
115```
116 
117## App Configuration Provider
118 
119### Load Configuration
120 
121```typescript
122import { load } from "@azure/app-configuration-provider";
123import { DefaultAzureCredential } from "@azure/identity";
124 
125const appConfig = await load(
126  process.env.AZURE_APPCONFIG_ENDPOINT!,
127  new DefaultAzureCredential(),
128  {
129    selectors: [
130      { keyFilter: "app:*", labelFilter: "production" },
131    ],
132    trimKeyPrefixes: ["app:"],
133  }
134);
135 
136// Map-style access
137const value = appConfig.get("settings:message");
138 
139// Object-style access
140const config = appConfig.constructConfigurationObject({ separator: ":" });
141console.log(config.settings.message);
142```
143 
144### Dynamic Refresh
145 
146```typescript
147const appConfig = await load(endpoint, credential, {
148  selectors: [{ keyFilter: "app:*" }],
149  refreshOptions: {
150    enabled: true,
151    refreshIntervalInMs: 30_000,  // 30 seconds
152  },
153});
154 
155// Trigger refresh (non-blocking)
156appConfig.refresh();
157 
158// Listen for refresh events
159const disposer = appConfig.onRefresh(() => {
160  console.log("Configuration refreshed!");
161});
162 
163// Express middleware pattern
164app.use((req, res, next) => {
165  appConfig.refresh();
166  next();
167});
168```
169 
170### Key Vault References
171 
172```typescript
173const appConfig = await load(endpoint, credential, {
174  selectors: [{ keyFilter: "app:*" }],
175  keyVaultOptions: {
176    credential: new DefaultAzureCredential(),
177    secretRefreshIntervalInMs: 7200_000,  // 2 hours
178  },
179});
180 
181// Secrets are automatically resolved
182const dbPassword = appConfig.get("database:password");
183```
184 
185## Feature Flags
186 
187### Create Feature Flag (Low-Level)
188 
189```typescript
190import {
191  featureFlagPrefix,
192  featureFlagContentType,
193  FeatureFlagValue,
194  ConfigurationSetting,
195} from "@azure/app-configuration";
196 
197const flag: ConfigurationSetting<FeatureFlagValue> = {
198  key: `${featureFlagPrefix}Beta`,
199  contentType: featureFlagContentType,
200  value: {
201    id: "Beta",
202    enabled: true,
203    description: "Beta feature",
204    conditions: {
205      clientFilters: [
206        {
207          name: "Microsoft.Targeting",
208          parameters: {
209            Audience: {
210              Users: ["user@example.com"],
211              Groups: [{ Name: "beta-testers", RolloutPercentage: 50 }],
212              DefaultRolloutPercentage: 0,
213            },
214          },
215        },
216      ],
217    },
218  },
219};
220 
221await client.addConfigurationSetting(flag);
222```
223 
224### Load and Evaluate Feature Flags
225 
226```typescript
227import { load } from "@azure/app-configuration-provider";
228import {
229  ConfigurationMapFeatureFlagProvider,
230  FeatureManager,
231} from "@microsoft/feature-management";
232 
233const appConfig = await load(endpoint, credential, {
234  featureFlagOptions: {
235    enabled: true,
236    selectors: [{ keyFilter: "*" }],
237    refresh: {
238      enabled: true,
239      refreshIntervalInMs: 30_000,
240    },
241  },
242});
243 
244const featureProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
245const featureManager = new FeatureManager(featureProvider);
246 
247// Simple check
248const isEnabled = await featureManager.isEnabled("Beta");
249 
250// With targeting context
251const isEnabledForUser = await featureManager.isEnabled("Beta", {
252  userId: "user@example.com",
253  groups: ["beta-testers"],
254});
255```
256 
257## Snapshots
258 
259```typescript
260// Create snapshot
261const snapshot = await client.beginCreateSnapshotAndWait({
262  name: "release-v1.0",
263  retentionPeriod: 2592000,  // 30 days
264  filters: [{ keyFilter: "app:*", labelFilter: "production" }],
265});
266 
267// Get snapshot
268const snap = await client.getSnapshot("release-v1.0");
269 
270// List settings in snapshot
271const settings = client.listConfigurationSettingsForSnapshot("release-v1.0");
272for await (const setting of settings) {
273  console.log(`${setting.key}: ${setting.value}`);
274}
275 
276// Archive/recover
277await client.archiveSnapshot("release-v1.0");
278await client.recoverSnapshot("release-v1.0");
279 
280// Load from snapshot (provider)
281const config = await load(endpoint, credential, {
282  selectors: [{ snapshotName: "release-v1.0" }],
283});
284```
285 
286## Labels
287 
288```typescript
289// Create settings with labels
290await client.setConfigurationSetting({
291  key: "database:host",
292  value: "dev-db.example.com",
293  label: "development",
294});
295 
296await client.setConfigurationSetting({
297  key: "database:host",
298  value: "prod-db.example.com",
299  label: "production",
300});
301 
302// Filter by label
303const prodSettings = client.listConfigurationSettings({
304  keyFilter: "*",
305  labelFilter: "production",
306});
307 
308// No label (null label)
309const noLabelSettings = client.listConfigurationSettings({
310  labelFilter: "\0",
311});
312 
313// List available labels
314for await (const label of client.listLabels()) {
315  console.log(label.name);
316}
317```
318 
319## Key Types
320 
321```typescript
322import {
323  AppConfigurationClient,
324  ConfigurationSetting,
325  FeatureFlagValue,
326  SecretReferenceValue,
327  featureFlagPrefix,
328  featureFlagContentType,
329  secretReferenceContentType,
330  ListConfigurationSettingsOptions,
331} from "@azure/app-configuration";
332 
333import { load } from "@azure/app-configuration-provider";
334 
335import {
336  FeatureManager,
337  ConfigurationMapFeatureFlagProvider,
338} from "@microsoft/feature-management";
339```
340 
341## Best Practices
342 
3431. **Use provider for apps** - `@azure/app-configuration-provider` for runtime config
3442. **Use low-level for management** - `@azure/app-configuration` for CRUD operations
3453. **Enable refresh** - For dynamic configuration updates
3464. **Use labels** - Separate configurations by environment
3475. **Use snapshots** - For immutable release configurations
3486. **Sentinel pattern** - Use a sentinel key to trigger full refresh
3497. **RBAC roles** - `App Configuration Data Reader` for read-only access
350