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.
Navigate to the Azure portal.
In the search bar, search for and select Static Web Apps.
Click on the Configuration option in the sidebar.
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.
Click on the Add Button to add a new app setting.
Enter a Name and Value.
Click OK.
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.
To ensure your new file with sensitive data isn't exposed publicly, add the following entry into your .gitignore file.
local.settings*.json
Next, make a copy of your local.settings.json file and name it local.settings.properties.json.
Inside the new file, remove all other data from the file except for the application settings and rename
Values
toproperties
.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:
- Static site name
- Resource group name
- Subscription ID
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"