In Azure Static Web Apps (SWA), customizing settings is often necessary—for example, modifying headers for specific needs. Although settings can be configured through the staticwebapp.config.json file, its placement (i.e., location) depends on the particular context (such as no framework, pre-built framework, or a framework that will be built during deployment).

This tutorial will guide you through where to place staticwebapp.config.json in different scenarios, along with configuration for popular CI/CD tools like Azure DevOps and GitHub Actions.

We will use the Access-Control-Allow-Origin response header as a validation example to confirm that the configurations are working correctly.

TOC:

A No Framework SWA
A Pre-Built Framework SWA (Using MkDocs as an Example)
A Framework that Builds During Deployment (Using React as an Example)
Environment Variables in Azure DevOps and GitHub Actions
References

A No Framework SWA

This example uses GitHub for CI/CD. Here is the directory structure and configuration:

For this tutorial, we’ll customize the Access-Control-Allow-Origin header, as shown below:

{
“globalHeaders”: {
“Access-Control-Allow-Origin”: “*”
}
}

The working directory is set to the project root (/). When creating the SWA, specify the App location as /.

After creation, wait for the GitHub Actions workflow to complete. Once deployed, you can check the page and see the customized Access-Control-Allow-Origin in the response headers for all requests.

While this method is straightforward, most users, including ourselves, typically use a framework. Below, I’ll explain how to apply custom configurations with different framework structures.

A Pre-Built Framework SWA (Using MkDocs as an Example)

Some projects prefer building or compiling locally, then deploying the pre-built resources to SWA. Since each framework has its own directory structure, you can specify where SWA should look for the config file by adjusting the App location.

In this example, we’re using MkDocs as a framework. Here’s how the configuration process works:

Place the staticwebapp.config.json file in the project root, although this may be incorrect. After building the project, the compiled output in this example is located in my-project/site.

Specify App location as my-project/site when creating the SWA.

After deployment, check the response headers. If the custom Access-Control-Allow-Origin header is not present, it indicates that the configuration file is incorrectly placed.

Move staticwebapp.config.json to the correct folder (my-project/site in this example).

Then, redeploy via GitHub Actions. After redeployment, the Access-Control-Allow-Origin header should appear in the response headers.

A Framework that Builds During Deployment (Using React as an Example)

Some projects are built dynamically during the CI/CD process, creating the build folder only at that stage. In this case, we need to predefine the path to the compiled folder and dynamically copy the configuration file there.

Using React as an example, we know the build folder will be named build after compilation. Place staticwebapp.config.json in the project root initially and set App location to build.

During deployment, GitHub Actions might show an error about the missing build directory.

This is expected; we’ll resolve it by modifying the CI/CD workflow as follows.

In the .github/workflows directory, add these steps to the workflow (yml) file:

# Step to install dependencies and build the React app
– name: Install dependencies and build the app
run: |
npm install
npm run build

# Step to create the build folder if it does not exist
– name: Ensure build folder exists
run: mkdir -p build

# Step to copy staticwebapp.config.json to the build folder
– name: Copy staticwebapp.config.json to build folder
run: cp “${{ github.workspace }}/staticwebapp.config.json” “${{ github.workspace }}/build/staticwebapp.config.json”

These steps install dependencies and build the React app, check for the existence of the build folder, and copy the staticwebapp.config.json from the project root to the target directory.

After updating the workflow and redeploying, you should see the configuration applied successfully.

Environment Variables in Azure DevOps and GitHub Actions

The example above includes the ${{ github.workspace }} variable, which points to the project’s root directory in GitHub Actions. If you’re using Azure DevOps, replace this variable with $(System.DefaultWorkingDirectory).

References:

Configure Azure Static Web Apps | Microsoft Learn

Deploy Mkdocs page on Azure Web App – Microsoft Community Hub

Accessing contextual information about workflow runs – GitHub Docs

Predefined variables – Azure Pipelines | Microsoft Learn

​Microsoft Tech Community – Latest Blogs –Read More