azure-static-web-apps

by github

Deploy static sites and serverless APIs to Azure with local development emulation and CLI automation. Provides local emulator ( swa start ) with API proxy, authentication simulation, and framework auto-detection for React, Vue, Angular, Next.js, and others Supports Azure Functions backends with Node.js, Python, and .NET runtimes; configure via staticwebapp.config.json for routes, auth rules, and headers Includes deployment workflow: swa init (auto-detects framework), swa build , swa start... npx skills add https://github.com/github/awesome-copilot --skill azure-static-web-apps Download ZIPGitHub36.2k

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.

• swa init - Required first step - auto-detects framework and creates swa-cli.config.json

• swa start - Run local emulator at http://localhost:4280

• swa login - Authenticate with Azure

• 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 # 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 # 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

• Create API folder:

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

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

• Set API runtime in staticwebapp.config.json:

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

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

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

• Test locally:

npx swa 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

• Create SWA resource in Azure Portal or via Azure CLI

• 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

• 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