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

Pin an exact CLI version in the project's package file, commit the lockfile, and run npx only after this local install so it resolves the pinned package. Pin the Azure Functions package the same way in the API folder.

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, after confirming the app name, subscription and target environment with the user. Start with a dry run or a preview deploy.

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 in trusted repositories only
• Edit the generated file only to customize settings after initialization
• In a repository you do not fully trust, use interactive swa init so the user approves the detected commands. Review the run and build commands in the generated file and the project's npm scripts with the user before running swa start or swa build.

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"
  }
}

Routes not listed stay public by default. Give admin and other sensitive paths their own route rules with allowed roles. Also define global response headers for a content security policy, nosniff content type handling and strict transport security.

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

Prefer interactive swa login. For service principals, supply the client secret from a CI secret store or the environment, and keep the literal secret value out of command lines, chat and logs. On shared machines, clear cached credentials with swa login --clear-credentials after use.

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. Review the command with the user before running it.
• --open, -o - Open browser automatically
• --ssl, -s - Enable HTTPS

swa deploy

Deploy to Azure Static Web Apps. Before every deploy, confirm the app name, subscription and target environment with the user, and default to a dry run or a preview deploy.

swa deploy                              # Deploy using config
swa deploy ./dist                       # Deploy specific folder
swa deploy --env production             # Deploy to production
swa deploy --dry-run                    # Preview without deploying

Get deployment token:

• Preferred, environment variable: SWA_CLI_DEPLOYMENT_TOKEN, set by the user or the CI secret store outside the agent session and scoped to the deploy command or CI deploy step only. Keep it out of the global environment and keep environment contents out of output.
• Azure Portal: Static Web App → Overview → Manage deployment token. The user copies the token straight into a repository or CI secret, keeping it out of the agent conversation.

Key flags:

• --env - Target environment (preview or production)
• --deployment-token, -d - Deployment token. Supply the token through the environment variable or swa login instead. Treat any token as secret, refer to it only by its variable name, and keep its value out of chat, command lines and logs.
• --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

Keep database connection strings in environment variables or app settings, keep credentials out of generated config files, and keep env and secret files out of version control.

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 - preview first, production only after explicit user confirmation
npx swa login
npx swa deploy --dry-run
npx swa deploy --env preview
# Run the next line only after the user confirms the app name, subscription and environment
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"

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}!` } };
    }
});

Anonymous functions rely on route rules with allowed roles in staticwebapp.config.json for access control. Validate and limit the length of user input such as the name parameter, and return it only inside JSON.

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 swa start ./dist --api-location ./api
# Access API at http://localhost:4280/api/message

Supported API runtimes: 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@v3
      - name: Build And Deploy
        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 }}
          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@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: close

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

Workflow security:

• Pin each action to a full commit hash with a version comment, and move to the current major release of the checkout action.
• Declare least privilege token permissions: read access to repository contents, plus write access to pull requests only on the build and deploy job when preview comments are wanted.
• Keep the plain pull request trigger. The privileged pull request target trigger exposes secrets to fork code.
• Use environment protection or approval for preview deploys. PR previews are publicly reachable, so restrict or turn them off when needed.
• Turn off checkout credential persistence when later steps do not need the workflow 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

Resolved configuration and verbose logs can contain tokens or credentials. Redact them before sharing or pasting into chat.