OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add github/awesome-copilot --skill azure-static-web-apps
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.
npx skills add github/awesome-copilot --skill azure-static-web-apps
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 manuallyVerify: 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):
staticwebapp.config.json (in app source or output folder) - This file CAN be created manually for runtime configuration:
Authenticate with Azure for deployment.
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.
Build frontend and/or API.
Flags: --app-location, -a | --api-location, -i | --output-location, -O | --app-build-command, -A | --api-build-command, -I
Start local development emulator.
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.
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.
Always run swa init before swa start or swa deploy. Do not manually create swa-cli.config.json.
api/src/functions/message.js):staticwebapp.config.json:swa-cli.config.json: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:
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:
{
"navigationFallback": {
"rewrite": "/index.html",
"exclude": ["/images/*", "/css/*"]
},
"routes": [
{ "route": "/api/*", "allowedRoles": ["authenticated"] }
],
"platform": {
"apiRuntime": "node:20"
}
}swa login # Interactive login
swa login --subscription-id <id> # Specific subscription
swa login --clear-credentials # Clear cached credentialsswa init # Interactive setup
swa init --yes # Accept defaultsswa build # Build using config
swa build --auto # Auto-detect and build
swa build myApp # Build specific configurationswa 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 serverswa 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 deployingswa db init --database-type mssql
swa db init --database-type postgresql
swa db init --database-type cosmosdb_nosql# 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 productionmkdir api && cd api
func init --worker-runtime node --model V4
func new --name message --template "HTTP trigger"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}!` } };
}
});{
"platform": { "apiRuntime": "node:20" }
}{
"configurations": {
"app": { "apiLocation": "api" }
}
}npx swa start ./dist --api-location ./api
# Access API at http://localhost:4280/api/messagename: 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: closeswa start --verbose log # Verbose output
swa deploy --dry-run # Preview deployment
swa --print-config # Show resolved configuration