Add examples and getting started instructions (#12)

Author: Eskibear

.gitignore

@@ -406,4 +406,7 @@ types/
 .env
 
 # npm pack
-*.tgz
+*.tgz
+
+# examples
+examples/package-lock.json

README.md

@@ -2,6 +2,36 @@
 
 The [Azure App Configuration](https://docs.microsoft.com/en-us/azure/azure-app-configuration/overview) provider for JavaScript enables developers to configure their applications using centralized configuration located in Azure App Configuration. 
 
+## Getting started
+
+### Prerequisites
+
+- An [Azure Subscription](https://azure.microsoft.com)
+- An [App Configuration](https://learn.microsoft.com/en-us/azure/azure-app-configuration/quickstart-azure-app-configuration-create?tabs=azure-portal) resource
+
+### Install the package
+
+```bash
+npm install @azure/app-configuration-provider
+```
+
+### Use the API
+
+```js
+import { load } from "@azure/app-configuration-provider";
+
+// Load settings from App Configuration as a readonly Map.
+const settings = await load("<app-configuration-connection-string>");
+
+// Consume the settings by calling `get(key)`, e.g.
+const value = settings.get("<key-of-a-config>");
+```
+
+
+## Examples
+
+See code snippets under [examples/](./examples/) folder.
+
 ## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
@@ -24,6 +54,6 @@ trademarks or logos is subject to and must follow
 Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
 Any use of third-party trademarks or logos are subject to those third-party's policies.
 
-# Data Collection
+## Data Collection
 
 The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry by setting the environment variable `AZURE_APP_CONFIGURATION_TRACING_DISABLED` to `TRUE`. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

SUPPORT.md

@@ -1,13 +1,3 @@
-# TODO: The maintainer of this repo has not yet edited this file
-
-**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project?
-
-- **No CSS support:** Fill out this template with information about how to file issues and get help.
-- **Yes CSS support:** Fill out an intake form at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). CSS will work with/help you to determine next steps.
-- **Not sure?** Fill out an intake as though the answer were "Yes". CSS will help you decide.
-
-*Then remove this first heading from this SUPPORT.MD file before publishing your repo.*
-
 # Support
 
 ## How to file issues and get help  
@@ -16,10 +6,8 @@ This project uses GitHub Issues to track bugs and feature requests. Please searc
 issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
 feature request as a new Issue.
 
-For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE 
-FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER
-CHANNEL. WHERE WILL YOU HELP PEOPLE?**.
+For help and questions about using this project, please ask a question in Stack Overflow with [azure-app-configuration](https://stackoverflow.com/questions/tagged/azure-app-configuration) tag.
 
 ## Microsoft Support Policy  
 
-Support for this **PROJECT or PRODUCT** is limited to the resources listed above.
+Support for this project is limited to the resources listed above.

examples/.env.template

@@ -0,0 +1,12 @@
+# You can define environment variables in .env file and load them with 'dotenv' package.
+# This is a template of related environment variables in examples.
+# To use this file directly, please rename it to .env
+APPCONFIG_CONNECTION_STRING=<app-configuration-connection-string>
+
+APPCONFIG_ENDPOINT=<app-configuration-endpoint>
+
+# Credential used to authenticate using Microsoft Entra ID (Azure AD) role-based authentication.
+# https://docs.microsoft.com/javascript/api/@azure/identity/environmentcredential
+AZURE_TENANT_ID=<AD tenant id or name>
+AZURE_CLIENT_ID=<ID of the user/service principal to authenticate as>
+AZURE_CLIENT_SECRET=<client secret used to authenticate to Azure AD>

examples/README.md

@@ -0,0 +1,38 @@
+# Examples for Azure App Configuration JavaScript Provider
+
+These examples show how to use the JavaScript Provider for Azure App Configuration in some common scenarios.
+
+## Prerequisites
+
+The sample programs are compatible with [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule).
+
+You need [an Azure subscription](https://azure.microsoft.com/free/) and the following Azure resources to run these sample programs:
+
+- [Azure App Configuration store](https://learn.microsoft.com/en-us/azure/azure-app-configuration/quickstart-azure-app-configuration-create?tabs=azure-portal)
+
+Samples retrieve credentials to access your App Configuration store from environment variables.
+Alternatively, edit the source code to include the appropriate credentials.
+See each individual sample for details on which environment variables/credentials it requires to function.
+
+## Setup
+
+To run the samples using the published version of the package:
+
+1. Install the dependencies using `npm`:
+
+    ```bash
+    npm install
+    ```
+
+2. There are two ways to run the samples using correct credentials:
+
+- Edit the file `.env.template`, adding the correct credentials to access your Azure App Configuration store and rename the file from `.env.template` to just `.env`.
+Then run the samples, it will read this file automatically.
+    ```bash
+    node helloworld.mjs
+    ```
+
+- Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform):
+    ```bash
+    npx cross-env APPCONFIG_CONNECTION_STRING="<appconfig connection string>" node helloworld.mjs
+    ```

examples/helloworld.mjs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+dotenv.config()
+
+/**
+ * This example retrives all settings with key following pattern "app.settings.*", i.e. starting with "app.settings.".
+ * With the option `trimKeyPrefixes`, it trims the prefix "app.settings." from keys for simplicity.
+ * Value of config "app.settings.message" will be printed.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_CONNECTION_STRING
+ */
+
+import { load } from "@azure/app-configuration-provider";
+const connectionString = process.env.APPCONFIG_CONNECTION_STRING;
+const settings = await load(connectionString, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }],
+    trimKeyPrefixes: ["app.settings."]
+});
+const message = settings.get("message");
+
+console.log(`Message from Azure App Configuration: ${message}`);

examples/helloworld_aad.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+dotenv.config()
+
+/**
+ * This example retrives all settings with key following pattern "app.settings.*", i.e. starting with "app.settings.".
+ * With the option `trimKeyPrefixes`, it trims the prefix "app.settings." from keys for simplicity.
+ * Value of config "app.settings.message" will be printed.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_ENDPOINT
+ * - AZURE_TENANT_ID
+ * - AZURE_CLIENT_ID
+ * - AZURE_CLIENT_SECRET
+ */
+
+import { load } from "@azure/app-configuration-provider";
+import { getDefaultAzureCredential } from "@azure/identity";
+const endpoint = process.env.APPCONFIG_ENDPOINT;
+const credential = getDefaultAzureCredential();
+const settings = await load(endpoint, credential, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }],
+    trimKeyPrefixes: ["app.settings."]
+});
+const message = settings.get("message");
+
+console.log(`Message from Azure App Configuration: ${message}`);

examples/package.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": {
+    "@azure/app-configuration-provider": "latest",
+    "@azure/identity": "^3.3.0",
+    "dotenv": "^16.3.1"
+  }
+}

examples/secretReference.mjs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+dotenv.config()
+
+/**
+ * Before you run it, please add a Key Vault reference with key "app.secret" in your App Configuration store.
+ * This example uses the same identity to authenticate with both App Configuration and Key Vault. Make sure that this identity has access to read secrets from Key Vault.
+ * Value of secret "app.secret" will be printed.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_ENDPOINT
+ * - AZURE_TENANT_ID
+ * - AZURE_CLIENT_ID
+ * - AZURE_CLIENT_SECRET
+ */
+
+import { load } from "@azure/app-configuration-provider";
+import { getDefaultAzureCredential } from "@azure/identity";
+const endpoint = process.env.APPCONFIG_ENDPOINT;
+const credential = getDefaultAzureCredential();
+const settings = await load(endpoint, credential, {
+    keyVaultOptions: {
+        credential: credential
+    }
+});
+const secretKey = "app.secret";
+const value = settings.get(secretKey);
+
+console.log(`Get the secret from keyvault key: ${secretKey}, value: ${value}`);