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

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