Configure application settings for Azure Static Web Apps

Application settings hold configuration 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 available as environment variables to the backend API of a static web app
  • Can be used to store secrets used in authentication configuration
  • Are encrypted at rest
  • Are copied to staging and production environments
  • May only be alphanumeric characters, ., and _

Important

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

To configure environment variables that are required to build your frontend web application, see Build configuration.

Prerequisites

  • An Azure Static Web Apps application
  • Azure CLI-required if you are using the command line

Configure API application settings for local development

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

Note

The local.settings.json file is only used for local development. Use the Azure portal to configure application settings for production.

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. In Node.js functions, for example, they're available in the process.env object.

const connectionString = process.env.DATABASE_CONNECTION_STRING;

The local.settings.json file isn't 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 configure your settings in Azure.

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

Configure application settings

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

Use the Azure portal

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

  1. Go to the Azure portal.

  2. Open your static web app.

  3. Select Environment variables in the sidebar.

  4. Select the environment to which you want to create environment variables. You can create variables per environment. When you create a pull request, staging environments are automatically created, and then promoted into production when you merge the pull request.

  5. Select + Add to add a new environment variable. Screenshot of Azure Static Web Apps environment variables view

  6. Enter a Name and Value.

  7. Select OK.

  8. Select Save.

Use the Azure CLI

Use the az staticwebapp appsettings command to update your settings in Azure.

In a terminal or command line, execute the following command to add or update a setting named message with a value of Hello world. Make sure to replace the placeholder <YOUR_APP_ID> with your value.

az staticwebapp appsettings set --name <YOUR_APP_ID> --setting-names "message=Hello world"

Tip

You can add or update multiple settings by passing multiple name-value pairs to --setting-names.

View application settings with the Azure CLI

In a terminal or command line, execute the following command. Make sure to replace the placeholder <YOUR_APP_ID> with your value.

az staticwebapp appsettings list --name <YOUR_APP_ID>

Delete application settings with the Azure CLI

In a terminal or command line, execute the following command to delete a setting named message. Make sure to replace the placeholder <YOUR_APP_ID> with your value.

az staticwebapp appsettings delete --name <YOUR_APP_ID> --setting-names "message"

Tip

Delete multiple settings by passing multiple setting names to --setting-names.