azure-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@1.9.7

Tip: Commit package-lock.json to version control to lock the full dependency tree and enable reproducible installs.

Verify: npx @azure/static-web-apps-cli@1.9.7 --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://raw.githubusercontent.com/Azure/static-web-apps-cli/v1.9.7/schema/swa-cli.config.schema.json",
  "configurations": {
    "app": {
      "appLocation": ".",
      "apiLocation": "api",
      "outputLocation": "dist",
      "appBuildCommand": "npm run build",
      "run": "npm run dev",
      "appDevserverUrl": "http://localhost:3000"
    }
  }
}

Note: The $schema URL above points directly to the versioned schema file in the upstream repository rather than the aka.ms redirect shortener, which can change without notice. Update the version segment when upgrading the CLI.

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

Note: --client-secret and --deployment-token values should be supplied via environment variables or a secrets manager, not as literal CLI arguments.

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:

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 (see security note below)
swa deploy --dry-run                    # Preview without deploying

⚠️ Security: Avoid passing tokens as CLI flags — flag values are visible in shell history (~/.bash_history, ~/.zsh_history) and in process listings while the process runs. Prefer the environment variable instead:

export SWA_CLI_DEPLOYMENT_TOKEN="<your-token>"
swa deploy --env production

The --deployment-token flag is shown above for reference only. When executing this command, use the environment variable form or a secrets manager rather than a literal token value in the command string.

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@1.9.7

# 2. Initialize - REQUIRED: creates swa-cli.config.json with auto-detected settings
npx @azure/static-web-apps-cli@1.9.7 init              # Interactive mode
# OR
npx @azure/static-web-apps-cli@1.9.7 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 @azure/static-web-apps-cli@1.9.7 start

# 5. Deploy
npx @azure/static-web-apps-cli@1.9.7 login
npx @azure/static-web-apps-cli@1.9.7 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"

1. Example function (api/src/functions/message.js):

const { app } = require('@azure/functions');

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request) => {
        const name = request.query.get('name') || 'World';
        return { jsonBody: { message: `Hello, ${name}!` } };
    }
});

1. Set API runtime in staticwebapp.config.json:

{
  "platform": { "apiRuntime": "node:20" }
}

1. Update CLI config in swa-cli.config.json:

{
  "configurations": {
    "app": { "apiLocation": "api" }
  }
}

1. Test locally:

npx @azure/static-web-apps-cli@1.9.7 start ./dist --api-location ./api
# Access API at http://localhost:4280/api/message

Supported API runtimes: node:18, node:20, node:22, dotnet:8.0, dotnet-isolated:8.0, python:3.10, python:3.11

Set Up GitHub Actions Deployment

1. Create SWA resource in Azure Portal or via Azure CLI
2. Link GitHub repository - workflow auto-generated, or create manually:

.github/workflows/azure-static-web-apps.yml:

name: Azure Static Web Apps CI/CD

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

jobs:
  build_and_deploy:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c  # v3.3.0
      - name: Build And Deploy
        uses: Azure/static-web-apps-deploy@a166e8b1503e38ed3a04cc8e89e5f0e25ceb36ac  # v1.1.2
        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

  close_pr:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: Azure/static-web-apps-deploy@a166e8b1503e38ed3a04cc8e89e5f0e25ceb36ac  # v1.1.2
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: close

Note: The SHA pins above correspond to actions/checkout@v3.3.0 and Azure/static-web-apps-deploy@v1.1.2. Verify SHA values at https://github.com/<owner>/<repo>/releases and update pins when upgrading action versions.

1. Add secret: Copy deployment token to repository secret AZURE_STATIC_WEB_APPS_API_TOKEN

Workflow settings:

• app_location - Frontend source path
• api_location - API source path
• output_location - Built output folder
• skip_app_build: true - Skip if pre-built
• app_build_command - Custom build command

Troubleshooting

Debug commands:

swa start --verbose log        # Verbose output
swa deploy --dry-run           # Preview deployment
swa --print-config             # Show resolved configuration