Configure application settings for Azure Static Web Apps Preview

Application settings hold configuration settings for values that may change, such as database connection strings. Adding application settings allows you to modify the configuration input to your app, without having to change application code.

Application settings are:

  • Encrypted at rest
  • Copied to staging and production environments

Application settings are also sometimes referred to as environment variables.

Important

The application settings described in this article only apply to the backend API of an Azure Static Web App.

For information on using environment variables with your frontend web application, see the docs for your JavaScript framework or Static site generator.

Prerequisites

  • An Azure Static Web Apps application
  • Azure CLI

Types of application settings

There are typically two aspects to an Azure Static Web Apps application. The first is the web application, or static content, which is represented by HTML, CSS, JavaScript, and images. The second is the back-end API, which is powered by an Azure Functions application.

This article demonstrates how to manage application settings for the back-end API in Azure Functions.

The application settings described in this article cannot be used or referenced in static web applications. However, many front-end frameworks and static site generators allow the use of environment variables during development. At build time, these variables are replaced by their values in the generated HTML or JavaScript. Since data in HTML and JavaScript is easily discoverable by site visitor, you want to avoid putting sensitive information in the front-end application. Settings that hold sensitive data are best located in the API portion of your application.

For information about how to use environment variables with your JavaScript framework or library, refer to the following articles for more detail.

JavaScript frameworks and libraries

Static site generators

About API App settings

APIs in Azure Static Web Apps are powered by Azure Functions, which allows you to define application settings in the local.settings.json file. This file defines application settings in the Values property of the configuration.

The following sample local.settings.json shows how to add a value for the DATABASE_CONNECTION_STRING.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "DATABASE_CONNECTION_STRING": "<YOUR_DATABASE_CONNECTION_STRING>"
  }
}

Settings defined in the Values property can be referenced from code as environment variables, available from the process.env object.

const connectionString = process.env.DATABASE_CONNECTION_STRING;

The local.settings.json file is not tracked by the GitHub repository because sensitive information, like database connection strings, are often included in the file. Since the local settings remain on your machine, you need to manually upload your settings to Azure.

Generally, uploading your settings is done infrequently, and isn't required with every build.

Uploading application settings

You can configure application settings via the Azure portal or with the Azure CLI.

Using the Azure portal

The Azure portal provides an interface for creating, updating and deleting application settings.

  1. Navigate to the Azure portal.

  2. In the search bar, search for and select Static Web Apps.

  3. Click on the Configuration option in the sidebar.

  4. Select the environment that you want to apply the application settings to. Staging environments are automatically created when a pull request is generated, and are promoted into production once the pull request is merged. You can set application settings per environment.

  5. Click on the Add Button to add a new app setting.

    Azure Static Web Apps configuration view

  6. Enter a Name and Value.

  7. Click OK.

  8. Click Save.

Using the Azure CLI

You can use the az rest command to do bulk uploads of your settings to Azure. The command accepts application settings as JSON objects in a parent property called properties.

The easiest way to create a JSON file with the appropriate values is to create a modified version of your local.settings.json file.

  1. To ensure your new file with sensitive data isn't exposed publicly, add the following entry into your .gitignore file.

    local.settings*.json
    
  2. Next, make a copy of your local.settings.json file and name it local.settings.properties.json.

  3. Inside the new file, remove all other data from the file except for the application settings and rename Values to properties.

    Your file should now look similar to the following example:

    {
      "properties": {
        "DATABASE_CONNECTION_STRING": "<YOUR_DATABASE_CONNECTION_STRING>"
      }
    }
    

The Azure CLI command requires a number of values specific to your account to run the upload. From the Overview window of your Static Web Apps resource, you have access to the following information:

  1. Static site name
  2. Resource group name
  3. Subscription ID

Azure Static Web Apps Overview

  1. From a terminal or command line, execute the following command. Make sure to replace the placeholders of <YOUR_STATIC_SITE_NAME>, <YOUR_RESOURCE_GROUP_NAME>, and <YOUR_SUBSCRIPTION_ID> with your values from the Overview window.

    az rest --method put --headers "Content-Type=application/json" --uri "/subscriptions/<YOUR_SUBSCRIPTION_ID>/resourceGroups/<YOUR_RESOURCE_GROUP_NAME>/providers/Microsoft.Web/staticSites/<YOUR_STATIC_SITE_NAME>/config/functionappsettings?api-version=2019-12-01-preview" --body @local.settings.properties.json
    

Important

The "local.settings.properties.json" file must be in the same directory where this command is run. This file can be named anything you like. The name is not significant.

View application settings with the Azure CLI

Application settings are available to view through the Azure CLI.

  • From a terminal or command line, execute the following command. Make sure to replace the placeholders <YOUR_SUBSCRIPTION_ID>, <YOUR_RESOURCE_GROUP_NAME>, <YOUR_STATIC_SITE_NAME> with your values.

    az rest --method post --uri "/subscriptions/<YOUR_SUBSCRIPTION_ID>/resourceGroups/<YOUR_RESOURCE_GROUP_NAME>/providers/Microsoft.Web/staticSites/<YOUR_STATIC_SITE_NAME>/listFunctionAppSettings?api-version=2019-12-01-preview"
    

Next steps