Create, configure, and deploy static websites with optional serverless API backends using the SWA CLI.
- GitHub stars
- 41,038
- Files
- 1
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the azure-static-web-apps skill do?
azure-static-web-apps is an agent skill. Create, configure, and deploy static websites with optional serverless API backends using the SWA CLI.
Summary generated from the skill's SKILL.md.
About the azure-static-web-apps skill
Deploying and managing static websites with serverless backends is what developers achieve using this skill. It provides access to the SWA CLI to handle the entire lifecycle of an Azure Static Web App, from local emulation to production deployment. An agent should load this tool when a user needs to initialize a new project, run a local development server with API proxying, or configure routing and authentication via staticwebapp.config.json.
The skill automates framework detection through the swa init command, which generates the necessary swa-cli.config.json file. It allows for the integration of Azure Functions as an API layer and supports various database connections including MSSQL, PostgreSQL, and CosmosDB. Users can manage deployments to production or preview environments using swa deploy, and can also set up automated CI/CD pipelines using GitHub Actions.
What an agent can do with it
- 1Initialize a new projectSet up a new Static Web App project by automatically detecting the frontend framework and creating configuration files.
- 2Run a local emulatorStart a local development environment that simulates the hosting environment and API proxying.
- 3Deploy to AzurePush the built application and its API to an Azure Static Web App environment.
- 4Connect a databaseConfigure connections to backend databases like PostgreSQL or CosmosDB.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the azure-static-web-apps skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the azure-static-web-apps skill in Claude Code
~/.claude/skills/azure-static-web-apps/SKILL.md
$ npx degit github/awesome-copilot/skills/azure-static-web-apps ~/.claude/skills/azure-static-web-appsInstall the azure-static-web-apps skill in Claude Code (project)
.claude/skills/azure-static-web-apps/SKILL.md
$ npx degit github/awesome-copilot/skills/azure-static-web-apps .claude/skills/azure-static-web-appsInstall the azure-static-web-apps skill in Codex
~/.agents/skills/azure-static-web-apps/SKILL.md
$ npx degit github/awesome-copilot/skills/azure-static-web-apps ~/.agents/skills/azure-static-web-appsInstall the azure-static-web-apps skill in Gemini CLI
~/.gemini/skills/azure-static-web-apps/SKILL.md
$ npx degit github/awesome-copilot/skills/azure-static-web-apps ~/.gemini/skills/azure-static-web-appsInstall the azure-static-web-apps skill in Claude.ai
npx degit github/awesome-copilot/skills/azure-static-web-apps azure-static-web-apps && zip -r azure-static-web-apps.zip azure-static-web-apps # claude.ai → Customize → Skills → + → Create skill → Upload a skill → azure-static-web-apps.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablegithub/awesome-copilot/skills/azure-static-web-apps is public and reachablegithub.com/github/awesome-copilot/tree/HEAD/skills/azure-sta ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/github/awesome-copilot/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/github/awesome-copilot/blob/HEAD/skills/azure-sta ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/github/awesome-copilot/blob/HEAD/skills/azure-sta ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 316 linesgithub.com/github/awesome-copilot/blob/HEAD/skills/azure-sta ↗Pass
SKILL.md
View on GitHubOverview
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 byswa 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 createsswa-cli.config.jsonswa start- Run local emulator athttp://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 initfor interactive setup with framework detection - Run
swa init --yesto 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 <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 <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 (previeworproduction)--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 pathapi_location- API source pathoutput_location- Built output folderskip_app_build: true- Skip if pre-builtapp_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 in this skill
1azure-static-web-apps skill questions
How do I install the azure-static-web-apps skill in Claude Code?
Run npx degit github/awesome-copilot/skills/azure-static-web-apps ~/.claude/skills/azure-static-web-apps. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the azure-static-web-apps skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I create the configuration files for a new SWA project?
You should always use the swa init command to auto-detect your framework and create the swa-cli.config.json file. Never create this file manually.
Can I manually create a configuration file for runtime settings?
Yes, you can manually create a staticwebapp.config.json file in your app source or output folder to manage routes, authentication, and headers.
How can I fix 404 errors on client-side routes?
To resolve 404 errors on client routes, add a navigationFallback with a rewrite to /index.html within your staticwebapp.config.json file.