azure-static-web-apps

Présentation générale

Azure Static Web Apps (SWA) héberge des frontends statiques avec des backends API serverless optionnels. La CLI SWA (swa) fournit des capacités d'émulation locale et de déploiement.

Fonctionnalités clés :

• Émulateur local avec proxy API et simulation d'authentification
• Détection et configuration automatiques du framework
• Déploiement direct vers Azure
• Support des connexions de base de données

Fichiers de configuration :

• swa-cli.config.json - Paramètres CLI, créé par swa init (ne jamais créer manuellement)
• staticwebapp.config.json - Configuration runtime (routes, authentification, en-têtes, runtime API) - peut être créé manuellement

Instructions générales

Installation

npm install -D @azure/static-web-apps-cli

Vérification : npx swa --version

Workflow de démarrage rapide

IMPORTANT : Utilisez toujours swa init pour créer les fichiers de configuration. Ne créez jamais manuellement swa-cli.config.json.

1. swa init - Étape requise en premier - détecte automatiquement le framework et crée swa-cli.config.json
2. swa start - Exécute l'émulateur local à http://localhost:4280
3. swa login - Authentifiez-vous avec Azure
4. swa deploy - Déployez vers Azure

Fichiers de configuration

swa-cli.config.json - Créé par swa init, ne pas créer manuellement :

• Exécutez swa init pour la configuration interactive avec détection du framework
• Exécutez swa init --yes pour accepter les défauts auto-détectés
• Modifiez le fichier généré uniquement pour personnaliser les paramètres après l'initialisation

Exemple de configuration générée (pour référence uniquement) :

{
  "$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 (dans le dossier source ou de sortie de l'application) - Ce fichier PEUT être créé manuellement pour la configuration runtime :

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*", "/css/*"]
  },
  "routes": [
    { "route": "/api/*", "allowedRoles": ["authenticated"] }
  ],
  "platform": {
    "apiRuntime": "node:20"
  }
}

Référence des commandes

swa login

Authentifiez-vous avec Azure pour le déploiement.

swa login                              # Connexion interactive
swa login --subscription-id <id>       # Abonnement spécifique
swa login --clear-credentials          # Effacer les identifiants en cache

Flags : --subscription-id, -S | --resource-group, -R | --tenant-id, -T | --client-id, -C | --client-secret, -CS | --app-name, -n

swa init

Configurez un nouveau projet SWA basé sur un frontend existant et une API (optionnelle). Détecte les frameworks automatiquement.

swa init                    # Configuration interactive
swa init --yes              # Accepter les défauts

swa build

Générez le frontend et/ou l'API.

swa build                   # Générer en utilisant la config
swa build --auto            # Auto-détection et génération
swa build myApp             # Générer une configuration spécifique

Flags : --app-location, -a | --api-location, -i | --output-location, -O | --app-build-command, -A | --api-build-command, -I

swa start

Démarrez l'émulateur de développement local.

swa start                                    # Servir depuis outputLocation
swa start ./dist                             # Servir un dossier spécifique
swa start http://localhost:3000              # Proxy vers le serveur de dev
swa start ./dist --api-location ./api        # Avec un dossier API
swa start http://localhost:3000 --run "npm start"  # Démarrage automatique du serveur de dev

Ports courants des frameworks : | Framework | Port | |-----------|------| | React/Vue/Next.js | 3000 | | Angular | 4200 | | Vite | 5173 |

Flags clés :

• --port, -p - Port de l'émulateur (défaut : 4280)
• --api-location, -i - Chemin du dossier API
• --api-port, -j - Port API (défaut : 7071)
• --run, -r - Commande pour démarrer le serveur de dev
• --open, -o - Ouvrir le navigateur automatiquement
• --ssl, -s - Activer HTTPS

swa deploy

Déployez vers Azure Static Web Apps.

swa deploy                              # Déployer en utilisant la config
swa deploy ./dist                       # Déployer un dossier spécifique
swa deploy --env production             # Déployer en production
swa deploy --deployment-token <TOKEN>   # Utiliser un token de déploiement
swa deploy --dry-run                    # Aperçu sans déployer

Obtenir le token de déploiement :

• Portail Azure : Static Web App → Présentation → Gérer le token de déploiement
• CLI : swa deploy --print-token
• Variable d'environnement : SWA_CLI_DEPLOYMENT_TOKEN

Flags clés :

• --env - Environnement cible (preview ou production)
• --deployment-token, -d - Token de déploiement
• --app-name, -n - Nom de la ressource SWA Azure

swa db

Initialisez les connexions de base de données.

swa db init --database-type mssql
swa db init --database-type postgresql
swa db init --database-type cosmosdb_nosql

Scénarios

Créer une SWA à partir d'un frontend et backend existants

Exécutez toujours swa init avant swa start ou swa deploy. Ne créez pas manuellement swa-cli.config.json.

# 1. Installer la CLI
npm install -D @azure/static-web-apps-cli

# 2. Initialiser - REQUIS : crée swa-cli.config.json avec les paramètres auto-détectés
npx swa init              # Mode interactif
# OU
npx swa init --yes        # Accepter les défauts auto-détectés

# 3. Générer l'application (si nécessaire)
npm run build

# 4. Tester localement (utilise les paramètres de swa-cli.config.json)
npx swa start

# 5. Déployer
npx swa login
npx swa deploy --env production

Ajouter un backend Azure Functions

1. Créer un dossier API :

   mkdir api && cd api
   func init --worker-runtime node --model V4
   func new --name message --template "HTTP trigger"

2. Exemple de fonction (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}! } }; } });

3. **Définir le runtime API** dans `staticwebapp.config.json` :
```json
{
  "platform": { "apiRuntime": "node:20" }
}

4. Mettre à jour la configuration CLI dans swa-cli.config.json :

   {
   "configurations": {
    "app": { "apiLocation": "api" }
   }
   }

5. Tester localement :

   npx swa start ./dist --api-location ./api
   # Accéder à l'API à http://localhost:4280/api/message

Runtimes API supportés : node:18, node:20, node:22, dotnet:8.0, dotnet-isolated:8.0, python:3.10, python:3.11

Configurer le déploiement GitHub Actions

1. Créer une ressource SWA dans le Portail Azure ou via Azure CLI
2. Lier le dépôt GitHub - workflow auto-généré, ou créer manuellement :

.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

3. Ajouter le secret : Copiez le token de déploiement dans le secret du dépôt AZURE_STATIC_WEB_APPS_API_TOKEN

Paramètres du workflow :

• app_location - Chemin source du frontend
• api_location - Chemin source de l'API
• output_location - Dossier de sortie généré
• skip_app_build: true - Ignorer si déjà généré
• app_build_command - Commande de build personnalisée

Dépannage

Commandes de débogage :

swa start --verbose log        # Sortie détaillée
swa deploy --dry-run           # Aperçu du déploiement
swa --print-config             # Afficher la configuration résolue