Azure Static Web Apps

GitHubOfficialFirst committed by tmeschterDistributed by GitHub

Skill
Tool integration
Cloud and DevOps
MIT
No issues found

From the author

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.

— the description by tmeschter

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Azure Static Web Apps (SWA) CLI is a command-line tool designed to streamline the development lifecycle of static web applications with serverless API backends. It provides a local emulation environment that mimics the Azure production environment, including API proxying and authentication simulation. The tool handles framework auto-detection, configuration management, and direct deployment to Azure, ensuring a consistent experience from local development to production.

What it does

Emulates the Azure Static Web Apps environment locally for testing.
Automatically detects frontend frameworks and configures project settings.
Manages deployment to Azure Static Web Apps directly from the command line.
Supports local authentication simulation and API proxying.
Facilitates database connection initialization for supported providers.
Provides configuration management for runtime settings and routing.

When to use it

When developing or deploying static frontends with optional serverless APIs to Azure.
When you need to test authentication and API routing locally before deployment.
When setting up CI/CD pipelines for Azure Static Web Apps.
When you need to configure custom routes, headers, or navigation fallbacks.

Advantages

Reduces environment parity issues by emulating production locally.
Simplifies project setup with automated framework detection.
Streamlines the deployment process with integrated authentication and CLI commands.
Provides a unified configuration approach for both local and cloud environments.

Usage examples

“How do I initialize a new Azure Static Web App project?”: Run 'npx swa init' in your project root to auto-detect your framework and generate the necessary configuration files.
“How can I test my application locally with an API?”: Use 'npx swa start ./dist --api-location ./api' to run the emulator, serving your static files and proxying API requests.
“How do I deploy my application to Azure?”: Authenticate using 'npx swa login' and then execute 'npx swa deploy --env production' to push your build to Azure.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/github/azure-static-web-apps/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip azure-static-web-apps.zip -d .agents/skills

Documentation by tmeschter

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

Authenticate with Azure for deployment.

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

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

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

Troubleshooting

Issue	Solution
404 on client routes	Add `navigationFallback` with `rewrite: "/index.html"` to `staticwebapp.config.json`
API returns 404	Verify `api` folder structure, ensure `platform.apiRuntime` is set, check function exports
Build output not found	Verify `output_location` matches actual build output directory
Auth not working locally	Use `/.auth/login/<provider>` to access auth emulator UI
CORS errors	APIs under `/api/*` are same-origin; external APIs need CORS headers
Deployment token expired	Regenerate in Azure Portal → Static Web App → Manage deployment token
Config not applied	Ensure `staticwebapp.config.json` is in `app_location` or `output_location`
Local API timeout	Default is 45 seconds; optimize function or check for blocking calls

Debug commands:

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

Files

ATTRIBUTION.mdAdded by AutoGineer877 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md9.3 KiB

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python, Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by

tmeschter

Publisher

GitHub (Official)

Distributed by

GitHub

Source

github/awesome-copilot · skills/azure-static-web-apps · commit 797337f

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

Contributors