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.jsonswa start - Run local emulator at http://localhost:4280swa login - Authenticate with Azureswa 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
swa login --subscription-id <id>
swa login --clear-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
swa init --yes
swa build
Build frontend and/or API.
swa build
swa build --auto
swa build myApp
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
swa start ./dist
swa start http://localhost:3000
swa start ./dist --api-location ./api
swa start http://localhost:3000 --run "npm start"
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
swa deploy ./dist
swa deploy --env production
swa deploy --deployment-token <TOKEN>
swa deploy --dry-run
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.
npm install -D @azure/static-web-apps-cli
npx swa init
npx swa init --yes
npm run build
npx swa start
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
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_TOKE
