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.
npxskills add github/awesome-copilot--skill azure-static-web-appsLoading…
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:
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 manuallynpm install -D @azure/static-web-apps-cli
Verify: npx swa --version
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.jsonswa start - Run local emulator at http://localhost:4280swa login - Authenticate with Azureswa deploy - Deploy to Azureswa-cli.config.json - Created by swa init, do not create manually:
swa init for interactive setup with framework detectionswa init --yes to accept auto-detected defaultsExample 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"
}
}
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
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
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
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 HTTPSDeploy 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:
swa deploy --print-tokenSWA_CLI_DEPLOYMENT_TOKENKey flags:
--env - Target environment (preview or production)--deployment-token, -d - Deployment token--app-name, -n - Azure SWA resource nameInitialize database connections.
swa db init --database-type mssql
swa db init --database-type postgresql
swa db init --database-type cosmosdb_nosql
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
mkdir api && cd api
func init --worker-runtime node --model V4
func new --name message --template "HTTP trigger"
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}!` } };
}
});
staticwebapp.config.json:{
"platform": { "apiRuntime": "node:20" }
}
swa-cli.config.json:{
"configurations": {
"app": { "apiLocation": "api" }
}
}
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
.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
AZURE_STATIC_WEB_APPS_API_TOKENWorkflow settings:
app_location - Frontend source pathapi_location - API source pathoutput_location - Built output folderskip_app_build: true - Skip if pre-builtapp_build_command - Custom build command| 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
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).