Build configuration for Azure Static Web Apps (2023)

Article
12.01.2023
8 minutes to read

Azure Static Web Apps build configuration is powered by either GitHub Actions or Azure Pipelines. Every site has a YAML configuration file that controls how a site is created and deployed. This article explains the structure and options of the file.

The following table lists the available configuration settings.

Property	description	Necessary
`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. When used with`skip_app_build: true`, this value is the app's build output location.	And
`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. When used with`skip_api_build: true`, this value is the build output location of the API.	no
`place of issue`	When your web app runs a build step, the output location is the folder where the public files are generated. For most projects, the`place of issue`is relative to`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 create the static content application. For example, to configure a production build for an Angular application, create an npm script named`building prod`to run`Construction type --prod`and enter`npm starte build-prod`as a custom command. If the field is left blank, the workflow attempts 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 create the Azure Functions API application.	no
`skip_app_build`	Set the value to`Is correct`to skip building the front-end app.	no
`skip_api_build`	Set the value to`Is correct`to skip creating the API functions.	no
`cwd` (Nur Azure Pipelines)	Absolute path to the working folder. Defaults to`$(System.DefaultWorkingDirectory)`.	no
`build_timeout_in_minutes`	Set this value to customize the build timeout. Defaults to`fifteen`.	no

These settings allow you to set up or disable GitHub actionsAzure-Pipelinesto perform continuous integration/continuous delivery (CI/CD) for your static web app.

File name and location

The GitHub Action
Azure-Pipelines

The configuration file is generated by GitHub and stored in the.github/workflowsFolder named according to the following format:azure-static-web-apps-<RANDOM_NAME>.yml.

Build-Konfiguration

The following example configuration monitors the repository for changes. When commits are pushed to themainlybranch, the application is built from theapp_locationFolders and files inplace of issueare made available to the public web. In addition, the application in theAPIFolder is available at the websiteAPIAway.

The GitHub Action
Azure-Pipelines

Name: Azure Static Web Apps CI/CDon: push: Branches: -main pull_request: types: [opened, synced, reopened, closed] Branches: -mainjobs: build_and_deploy_job: if: github.event_name == "push" || (github.event_name == 'pull_request' && github.event.action != 'closed') is executed 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 path relative to repository root api_location: "api" # API source path relative to repository root - optional output_location: "public" # Created app TOC relative to app_location - optional ###### End of repository/build configs ###### close_pull_request_job: if: github.event_name == 'pull_request' && github.event.action == 'closed' running on: ubuntu-latest name: pull-request close en 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:

DiemainlyBranch is monitored for commits.
A GitHub Actions workflow istriggeredif a pull request on themainlyBranch is: opened, synchronized, reopened, or closed.
Diebuild_and_deploy_jobRuns when you push commits or open a pull request on the branch listed inanProperty.
Dieapp_locationpoints to theThoseFolder containing the source files for the web app. To set this value to the repository root, use/.
Dieapi_locationpoints to theAPIFolder containing the Azure Functions application for the website's API endpoints. To set this value to the repository root, use/.
Dieplace of issuepoints to thepubliclyFolder containing the final version of the app's source files. It's relative toapp_location. For .NET projects, the location is relative to the publish output folder.

Do not change the values forrepo_token,action, andazure_static_web_apps_api_tokenas set for you by Azure Static Web Apps.

Custom build commands

With Node.js applications, you can control exactly what commands run during the app or API building process. The following example shows how to define Build with values forapp_build_commandandapi_build_command.

note

Currently you can only defineapp_build_commandandapi_build_commandfor Node.js builds. To specify the Node.js version, use theThe enginefield inPackage.jsonFile.

The GitHub Action
Azure-Pipelines

...mit: 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 starte build-api-prod'

Skip creating a front-end app

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

To skip creating the front-end app:

Sentenceapp_locationto the location of the files you want to deploy.
Sentenceskip_app_buildtoIs correct.
Sentenceplace of issueto an empty string ('').

note

Make sure you have yoursstaticwebapp.config.jsonFile also copied to theExitDirectory.

The GitHub Action
Azure-Pipelines

...mit: 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

Skip creating the API

If you want to skip creating the API, you can bypass the automatic creation and provide the API created in a previous step.

Steps to skip creating the API:

Imstaticwebapp.config.jsonfile, adjustapiRuntimeto the correct runtime and version. Refer toConfigure Azure Static Web Appsfor the list of supported runtimes and versions.
```
{ "Platform": { "apiRuntime": "Nodes: 16" }}
```
Sentenceskip_api_buildtoIs correct.
Sentenceapi_locationin the folder with the created API app to deploy. This path is relative to the repository root in GitHub Actions andcwdin Azure-Pipelines.

The GitHub Action
Azure-Pipelines

...with: azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }} repo_token: ${{ secrets.GITHUB_TOKEN }} action: 'upload' app_location: "src" # App source path relative to repository root api_location: "api" # API source path relative to repository root - optional output_location: "public" # Built app table of contents relative to app_location - optional skip_api_build: true

Extend build timeout

By default, app and API builds are limited to 15 minutes. You can extend the build timeout by using thebuild_timeout_in_minutesProperty.

The GitHub Action
Azure-Pipelines

...mit: 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' build_timeout_in_minutes: 30

environment variables

You can set environment variables for your build through theenvSection of a job's configuration.

The GitHub Action
Azure-Pipelines

...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: # Umgebung hinzufügen Variablen hier 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 customize the configuration to target a single app.

To target a workflow file to a single app, specify paths in thepressandpull_requestsections.

The GitHub Action
Azure-Pipelines

When you set up a monorepo, any static app configuration is limited to files for a single app only. The various workflow files live side by side in the repositories.github/workflowsMaps.

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

The following example shows how to add apathsnode topressandpull_requestSections of a file namedazure-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, sync, reopened, closed] Branches: - Main paths: - app1/** - api1/** - .github/workflows/azure-static-web-apps-purple-pond.yml

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

All files within theapp1Maps
All files within theapi1Maps
Changes to the appazure-static-web-apps-purple-pond.ymlworkflow file

Next Steps

Review pull requests in pre-production environments