/azure-static-web-apps

name: azure-static-web-apps
description: Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps.

Overview

Azure Static Web Apps (SWA) hosts static frontends with optional serverless API backends. The SWA CLI (`swa`) provides local development emulation and deployment capabilities.

**Key features:**

• Local emulator with API proxy and auth simulation
• Framework auto-detection and configuration
• Direct deployment to Azure
• Database connections support

**Config files:**

• `swa-cli.config.json` - CLI settings, **created by `swa init`** (never create manually)
• `staticwebapp.config.json` - Runtime config (routes, auth, headers, API runtime) - can be created manually

General Instructions

Installation

npm install -D @azure/static-web-apps-cli

Verify: `npx swa --version`

Quick Start Workflow

**IMPORTANT: Always use `swa init` to create configuration files. Never manually create `swa-cli.config.json`.**

1. `swa init` - **Required first step** - auto-detects framework and creates `swa-cli.config.json` 2. `swa start` - Run local emulator at `http://localhost:4280` 3. `swa login` - Authenticate with Azure 4. `swa deploy` - Deploy to Azure

Configuration Files

**swa-cli.config.json** - Created by `swa init`, do not create manually:

• Run `swa init` for interactive setup with framework detection
• Run `swa init --yes` to accept auto-detected defaults
• Edit the generated file only to customize settings after initialization

Example of generated config (for reference only):

{
  "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
  "configurations": {
    "app": {
      "appLocation": ".",
      "apiLocation": "api",
      "outputLocation": "dist",
      "appBuildCommand": "npm run build",
      "run": "npm run dev",
      "appDevserverUrl": "http://localhost:3000"
    }
  }
}

**staticwebapp.config.json** (in app source or output folder) - This file CAN be created manually for runtime configuration:

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*", "/css/*"]
  },
  "routes": [
    { "route": "/api/*", "allowedRoles": ["authenticated"] }
  ],
  "platform": {
    "apiRuntime": "node:20"
  }
}

Command-line Reference

swa login

Authenticate with Azure for deployment.

swa login                              # Interactive login
swa login --subscription-id <id>       # Specific subscription
swa login --clear-credentials          # Clear cached credentials

**Flags:** `--subscription-id, -S` | `--resource-group, -R` | `--tenant-id, -T` | `--client-id, -C` | `--client-secret, -CS` | `--app-name, -n`

swa init

Configure a new SWA project based on an existing frontend and (optional) API. Detects frameworks automatically.

swa init                    # Interactive setup
swa init --yes              # Accept defaults

swa build

Build frontend and/or API.

swa build                   # Build using config
swa build --auto            # Auto-detect and build
swa build myApp             # Build specific configuration

**Flags:** `--app-location, -a` | `--api-location, -i` | `--output-location, -O` | `--app-build-command, -A` | `--api-build-command, -I`

swa start

Start local development emulator.

swa start                                    # Serve from outputLocation
swa start ./dist                             # Serve specific folder
swa start http://localhost:3000              # Proxy to dev server
swa start ./dist --api-location ./api        # With API folder
swa start http://localhost:3000 --run "npm start"  # Auto-start dev server

**Common framework ports:** | Framework | Port | |-----------|------| | React/Vue/Next.js | 3000 | | Angular | 4200 | | Vite | 5173 |

**Key flags:**

• `--port, -p` - Emulator port (default: 4280)
• `--api-location, -i` - API folder path
• `--api-port, -j` - API port (default: 7071)
• `--run, -r` - Command to start dev server
• `--open, -o` - Open browser automatically
• `--ssl, -s` - Enable HTTPS

swa deploy

Deploy to Azure Static Web Apps.

swa deploy                              # Deploy using config
swa deploy ./dist                       # Deploy specific folder
swa deploy --env production             # Deploy to production
swa deploy --deployment-token <TOKEN>   # Use deployment token
swa deploy --dry-run                    # Preview without deploying

**Get deployment token:**

• Azure Portal: Static Web App → Overview → Manage deployment token
• CLI: `swa deploy --print-token`
• Environment variable: `SWA_CLI_DEPLOYMENT_TOKEN`

**Key flags:**

• `--env` - Target environment (`preview` or `production`)
• `--deployment-token, -d` - Deployment token
• `--app-name, -n` - Azure SWA resource name

swa db

Initialize database connections.

swa db init --database-type mssql
swa db init --database-type postgresql
swa db init --database-type cosmosdb_nosql

Scenarios

Create SWA from Existing Frontend and Backend

**Always run `swa init` before `swa start` or `swa deploy`. Do not manually create `swa-cli.config.json`.**

# 1. Install CLI
npm install -D @azure/static-web-apps-cli

# 2. Initialize - REQUIRED: creates swa-cli.config.json with auto-detected settings
npx swa init              # Interactive mode
# OR
npx swa init --yes        # Accept auto-detected defaults

# 3. Build application (if needed)
npm run build

# 4. Test locally (uses settings from swa-cli.config.json)
npx swa start

# 5. Deploy
npx swa login
npx swa deploy --env production

Add Azure Functions Backend

1. **Create API folder:**

mkdir api && cd api
func init --worker-runtime node --model V4
func new --name message --template "HTTP trigger