---
name: ado-azure-static-web-apps
description: >-
  Azure Pipelines deploy to Azure Static Web Apps using AzureStaticWebApp@0
  with pre-built artifacts, skip_app_build, environment-scoped deployment tokens,
  and stage conditions on branches or tags. Documents staticwebapp.config.json
  and navigationFallback for SPA routers (Vue/React). Use after ado-nodejs-build
  publishes a dist folder.
---

# Azure Pipelines: Azure Static Web Apps

## Prerequisites

- A **Build** stage that produces a static folder (`dist` or similar) via **`ado-nodejs-build`** (or equivalent) and **`PublishBuildArtifacts@1`**.
- Library secrets for deployment tokens (e.g. `DEPLOYMENT_TOKEN_STAGING`, `DEPLOYMENT_TOKEN_PRODUCTION`).
- An Azure Static Web Apps resource per environment (or slots) with tokens available in the portal.

## `staticwebapp.config.json` (required for SPA routers)

Place `staticwebapp.config.json` next to `package.json` and **copy it into the build output** (e.g. `dist/`) before `PublishBuildArtifacts@1`. Without it at the **root of the deployed app**, Vue Router, React Router, and similar client-side routes return **404** on refresh or deep links.

Include at least `navigationFallback` so unknown paths rewrite to `index.html` (tune `exclude` for real static assets):

```json
{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]
  }
}
```

Official reference: [Azure Static Web Apps configuration](https://learn.microsoft.com/azure/static-web-apps/configuration#example-configuration-file).

## Deploy task

Typical `AzureStaticWebApp@0` inputs when the site is already built:

| Input | Value |
|-------|--------|
| `workingDirectory` | `$(Pipeline.Workspace)` |
| `app_location` | `./<artifactName>` — folder from artifacts (must match `ArtifactName`) |
| `skip_app_build` / `skip_api_build` | `true` |
| `azure_static_web_apps_api_token` | `$(DEPLOYMENT_TOKEN_*)` secret |

## Stage gating

- **Staging** — allow specific branches, e.g. `refs/heads/main` and/or `refs/heads/development`.
- **Production** — often `startsWith(variables['Build.SourceBranch'], 'refs/tags/')` or a dedicated release branch.

Use `environment: Staging` / `Production` on `deployment` jobs for approval gates.

## Triggers

Use `pr:` with `autoCancel` and `trigger.batch` when you want fewer overlapping PR builds—align with repo branch policy.

## YAML

See [reference.md](reference.md).