Build configuration for Azure Static Web Apps

The Azure Static Web Apps build configuration is powered either by Azure Pipelines, or GitHub Actions. Each site has a YAML configuration file that controls how a site is built and deployed. This article explains the file's structure and options.

The following table lists the available configuration settings.

Property Description Required
app_location This folder contains the source code for your front-end application. The value is relative to the repository root in GitHub and the current working folder in Azure DevOps. Yes
api_location This folder that contains the source code for your API application. The value is relative to the repository root in GitHub and the current working folder in Azure DevOps. No
output_location If your web app runs a build step, the output location is the folder where the public files are generated. For most projects, the output_location is relative to the app_location. However, for .NET projects, the location is relative to the publish output folder. No
app_build_command For Node.js applications, you can define a custom command to build the static content application.

For example, to configure a production build for an Angular application create an npm script named build-prod to run ng build --prod and enter npm run build-prod as the custom command. If left blank, the workflow tries to run the npm run build or npm run build:azure commands.
No
api_build_command For Node.js applications, you can define a custom command to build the Azure Functions API application. No
skip_app_build Set the value to true to skip building the front-end app. No

With these settings, you can set up GitHub Actions or Azure Pipelines to run continuous integration/continuous delivery (CI/CD) for your static web app.

Note

Currently, you can only define app_build_command and api_build_command for Node.js builds.

File name and location

The configuration file is generated by GitHub and stored in the .github/workflows folder, named using the following format: azure-static-web-apps-<RANDOM_NAME>.yml.

Build configuration

The following sample configuration monitors the repository for changes. As commits are pushed to the main branch, the application is built from the app_location folder and files in the output_location are served to the public web. Additionally, the application in the api folder is available under the site's api path.

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations ######
          app_location: "src" # App source code path
          api_location: "api" # Api source code path - optional
          output_location: "public" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: "close"

In this configuration:

  • The main branch is monitored for commits.
  • A GitHub Actions workflow is triggered when a pull request on the main branch is: opened, synchronized, reopened, or closed.
  • The build_and_deploy_job executes when you push commits or open a pull request against the branch listed in the on property.
  • The app_location points to the src folder that contains the source files for the web app.
  • The api_location points to the api folder that contains the Azure Functions application for the site's API endpoints.
  • The output_location points to the public folder that contains the final version of the app's source files.

Don't change the values for repo_token, action, and azure_static_web_apps_api_token as they're set for you by Azure Static Web Apps.

Custom build commands

For Node.js applications, you can take fine-grained control over what commands run during the app or API build process. The following example shows how to define build with values for app_build_command and api_build_command.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: '/'
  api_location: 'api'
  output_location: 'dist'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'

Skip building front-end app

If you need full control of the build for your front-end app, you can bypass the automatic build and deploy the app built in a previous step.

To skip building the front-end app:

  • Set app_location to the location the files you want to deploy.
  • Set skip_app_build to true.
  • Set output_location to an empty string ('').
...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src/dist'
  api_location: 'api'
  output_location: ''
  skip_app_build: true

Note

You can only skip the build for the front-end app. The API is always built if it exists.

Environment variables

You can set environment variables for your build via the env section of a job's configuration.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'

env: # Add environment variables here
  HUGO_VERSION: 0.58.0

Monorepo support

A monorepo is a repository that contains code for more than one application. By default, the workflow tracks all files in a repository, but you can adjust the configuration to target a single app.

To target a workflow file to a single app, you specify paths in the push and pull_request sections.

When you set up a monorepo, each static app configuration is scoped to only files for a single app. The different workflow files live side by side in the repository's .github/workflows folder.

├── .github
│   └── workflows
│       ├── azure-static-web-apps-purple-pond.yml
│       └── azure-static-web-apps-yellow-shoe.yml
│
├── app1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── app2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
├── api1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── api2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
└── README.md

The following example demonstrates how to add a paths node to the push and pull_request sections of a file named azure-static-web-apps-purple-pond.yml.

on:
  push:
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml

In this example, only changes made to following files trigger a new build:

  • Any files inside the app1 folder
  • Any files inside the api1 folder
  • Changes to the app's azure-static-web-apps-purple-pond.yml workflow file

Next steps