Configure File in Azure Static Web Apps

Azure Static Web Apps (SWA) often requires you to customize settings, such as modifying headers to suit your specific needs. You can configure settings via the staticwebapp.config.json file, but its location is (i.e. location) It depends on the specific context (e.g. no framework, pre-built framework, or framework to be built during deployment).

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

Let’s use the Access-Control-Allow-Origin response header as a verification example to ensure that our configuration is working correctly.

index:

• No framework SWA
• Pre-built framework SWA (using MkDocs as an example)
• Frameworks that are built during deployment (using React as an example)
• Environment variables in Azure DevOps and GitHub Actions
• References

No framework SWA

This example uses GitHub for CI/CD. The directory structure and organization is as follows:

In this tutorial, we will 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 a SWA, specify the app location as /.

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

This method is simple, but most people, including us, usually use frameworks. Below we will explain how to apply custom configurations to various framework structures.

Pre-built framework SWA (using MkDocs as an example)

Some projects prefer to build or compile locally and then deploy the pre-built resources to SWA. Because each framework has its own directory structure, you can adjust your app location to specify where SWA should look for configuration files.

This example uses MkDocs as the framework. Here’s how the configuration process works:

Place the staticwebapp.config.json file in the root of your project. This may not be correct. After building the project, the compiled output of this example is in my-project/site.

When creating the SWA, specify the app location as my-project/site.

Check the response headers after deployment. The absence of a custom Access-Control-Allow-Origin header indicates a misplaced configuration file.

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

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

Frameworks that are built during deployment (using React as an example)

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

For example, with React, you will notice that after compilation the build folder is named build. Initially place staticwebapp.config.json in the root of your project and set the location of the app you want to build.

During deployment, GitHub Actions may display errors about missing build directories.

This is expected. Let’s fix this by modifying our CI/CD workflow as follows:

Add the following steps to your workflow (yml) file in the .github/workflows directory.

      # 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, ensure the build folder exists, and copy staticwebapp.config.json from the project root to the target directory.

After updating and redeploying the workflow, you can see that the configuration was applied successfully.

Environment variables in Azure DevOps and GitHub Actions

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

References:

Configure Azure Static Web App | microsoft run

Deploy Mkdocs Pages to Azure Web App – Microsoft Community Hub

Access contextual information about workflow execution – GitHub Docs

Predefined variables – Azure Pipelines | microsoft run